JamesArmes.com

Barcamp Harrisburg: Setting up shop with Drupal Commerce

jarmes — Sat, 31 Mar 2012 23:23:18 +0000

Setting up shop with Drupal Commerce on Prezi

Above is the presentation I gave at this year's Barcamp Harrisburg. Below you can find links that were included in the presentation as well as some additional resources. Also, don't forget to vote for AllPlayers.com in the Blue Drop Awards.

Tags:

Drupal

The New Jimmy's Sandbox

jarmes — Wed, 07 Apr 2010 00:16:12 +0000

As you can see, Jimmy's Sandbox has seen a bit of a face lift. This represents several weeks of planning and implementation. Now that the new design is in place, you should start seeing more frequent post regarding Drupal, PHP, Web Services and many other topics related to web development.

Your Thoughts

Do you have any thoughts on the new design? Good or bad I want to hear it. How about something you would like to see a new post about? Whatever it is, leave your thoughts in the comment section below.

Tags:

Jimmy's Sandbox

Jimmy's Fridge

jarmes — Thu, 25 Feb 2010 13:29:10 +0000

This is in response to My Fridge by Dries Buytaert.

Drupal 6 Performance on GoDaddy

jarmes — Wed, 06 Jan 2010 23:23:25 +0000

I have been using Google's Page Speed tool to help improve the the load times of this site. In doing so, I discovered that I never configured any of the performance settings provided by Drupal. I also discovered that GoDaddy does not use mod_gzip or mod_deflate to compress the documents being requested.

Drupal's Performance Settings

Drupal comes prepackaged with performance tuning options. These options include caching and CSS/JavaScript optimization. By enabling these features, I saw a dramatic decrease in load times for Jimmy's Sandbox. You can view the performance settings for your site at /admin/settings/performance.

Caches

Drupal provides both a page cache and a block cache. The page cache only affects anonymous users. While enabled, it will cache pages so that it does not need to re-render them for each request. When a page is updated, the cache is cleared. There are three levels of page caching:

Disabled: No caching will occur and each request will have to wait for the page to be rendered.
Normal: Recommend for most sites and does not cause any side effects.
Aggressive : Skips the loading and unloading of all modules when serving a cached page. This can cause side effects with modules that rely on this behavior (ie. Statistics). If you visit the performance settings of your site, you will be notified of any modules that are incompatible with aggressive caching (see below).

Drupal also allows you to provide a minimum cache lifetime. This will prevent the cache for both pages and blocks from being cleared before that time. The available options range from one minute to one day.

The page compression option will allow Drupal to compress cached pages as they are sent to the browser. This saves on bandwidth and can provide quite a performance boost for larger pages. Since HTML is text, it compresses quite well. Enabling this option helps to mitigate the fact that GoDaddy does not have any compression of their own.

Unlike the page cache, the block cache can provide a performance boost to all users. The block cache is similar to the page cache in that it prevents individual blocks from having to be rendered on each page load. If you have any modules that define content access restrictions, such as Node Privacy By Role, this setting cannot be enabled. I have several blocks on that provide dynamic content and have not run into any issues by enabling the block cache.

CSS/JavaScript Optimizations

Drupal's CSS and JavaScript optimizations are really quite simple. When enabled, they combine all JavaScript into a single file and all CSS into a single file. Both files are then cached and the CSS file is compressed. If you have not created your files directory, or have configured your files to be private, these options cannot be enabled.

Google Analytics Optimizations

If you are using the Google Analytics module by budda, you can cache the JavaScript file that is normally stored on Google's servers. This prevents the browser from having to perform an additional DNS lookup. The cache is updated once a day and can be enabled from the "Advanced settings" field group at /admin/settings/googleanalytics. It is important that you wait until Google has validated your site before enabling this option.

JavaScript Compression

Unlike the CSS cache, cached JavaScript is not compressed. To get around this, I use the SmartCache module. The module requires your Apache server to have mod_rewrite enabled to redirect requests for all JavaScript and CSS files to a script provided by the module. When a file is requested, the script creates a compressed version of the file and serves that up instead of the plain text version. The compressed file is then cached

This requires some manual setup to get working. There is no .info file so Drupal will not recognize it as an actual module, but that's okay since the module doesn't actually interact with Drupal. There are some configuration options in the load.php file that need setup and a line will need to be added to you .htaccess file. To clear the cache before the next scheduled cache clear, just clear the files out of the cache directory. Basically just read the README.txt file that comes packaged with the module and you will be fine.

What Performance Tips Do You Have?

That's just a quick run through of the performance improvements I have used here on Jimmy's Sandbox. The are certainly other options out there, such as minifying JavaScript. So what do you use to improve performance on your site? Let us know by leaving a comment below. While you're at it, while not subscribe to the Jimmy's Sandbox feed and be notified of new posts that may include other performance improvements.

Tags:

Drupal

GoDaddy

Performance

Simple Tips For Repsonding To A Web Developer Job Posting

jarmes — Mon, 21 Dec 2009 02:43:52 +0000

I was recently tasked with hiring a web developer for a redesign of workxpress.com. I was surprised at the number of poor quality responses I received. The original post can be found at http://drupal.org/node/602292. Looking back, I should have included more details in my post, but that still doesn't excuse the poor quality of some of these emails.

I have taken examples from many of the emails that I have received for us to analyze. Names and URLs have been changed to protect the identities of the individuals. So, without further ado, I present you with some simple tips when responding to a web developer job post.

1. Use a professional email address

I don't think a lot of people realize how important their email address can be. I'm not going to spend a lot of time on this, but suffice it to say that you will not get taken seriously replying to a job post using an email like awesomejedi@yahoo.com. Check out the Men With Pens post Is Your Email Address Losing You Clients? for more on this subject.

2. Use a professional yet personal greeting

The greeting is the first thing in your email to be read. I think everybody knows this, but not everybody seems to think about their greeting. So what makes a greeting professional yet personal? Professional is easy, avoid using words you wouldn't use when meeting an interviewer for the first time (such as "Hey"). Personal is easy as well, just use the persons name. For example, a greeting like "James" or "Dear James" would suffice. The worst offender I received had to be "hi and thanks-".

3. Use proper capitalization

We all know not to type in all caps, but all lowercase doesn't send the right message either. Make sure you capitalize the first letter in names and the first word of each sentence. See below for some examples of poor capitalization. I find the second example to be curious, as he capitalized the supported browsers, but nothing else.

Example 1:

saw your post-
perhaps i can provide the service you need

i am a drupal samurai for hire
based in buffalo, new york usa

Example 2:

output will be drupal theme, valid html/css, major browser compatibility (IE,FF,Safari). additional sub template add $75

4. Add some descriptions to your examples

Including example sites in your response is always a good idea. When providing examples, give some details on each. Example 3 below shows a poor presentation of sites you have worked on. Example 4 shows a much better presentation that includes descriptions of what the web developer did on each.

Example 3:

http://www.example.com (usa, media)
http://www.foo.com (usa. media)
http://www.bar.co.uk (project services, uk)
http://www.baz.ca/web (infotech, canada)

Example 4:

http://www.example.com - I project managed and/or wrote the HTML and CSS for every site in this portfolio with the exception of Foo, Bar, and Baz. Some of the links in the portfolio there are broken, but can be fixed by replacing 'ex4' with 'ex4mediagroup' in the URL; the company no longer does business under that name so I don't think they're maintaining it anymore.

http://www.foo.com and http://www.foo.com/smarty/templates/default/styles.css - This is one of the sites that I wrote the HTML and CSS for. This site and the others in this portfolio were built on an in-house CMS using the Smarty templating system.

http://www.bar.co.uk - I worked in some degree with several of the projects in the portfolio at Foo, however the greatest involvement I had was with specific projects that are still in progress or not in the portfolio.

http://www.baz.ca/web - This was the largest project we worked with while I was at Foo, and I both project managed it through most of it's duration and did much of the Drupal configuration, including extensive work with views and Ubercart.

5. Use complete sentences

This is another no brainier, or so I thought. Use complete sentences with proper punctuation. Run on sentences and simple three word phrases don't look very professional. The following example could have easily been several sentences and looked much more professional.

Example 5:

I went through your post , i am drupal developer. I am good hand in css. I done following project

6. Use correct grammar

While I understand English is not everyones first language, you should have a firm understanding of grammar before responding in any language. If I don't feel that I will be able to communicate with you, I'm not likely to hire you. The following three examples clearly demonstrate a lack of proper grammer.

Example 6:

I am John who have experiences in designing and developing drupal websites for national as well as international clients. I saw your post at drupal form and would like know more about the job.

Example 7:

We are Foo Bar, Inc. located in Redwood City, CA. We experience designing and redesigning Drupal based sites

Example 8:

I had a chance to look at your requirement about ,Hireing a drupal developer to complete your requirement ,We could be of great help to you.

Your turn

What are your thoughts on some of these tips? Do you have any other advice for those replying to a job post? Please share you thoughts in the comments below.

Tags:

Drupal

Freelance

Using the WorkXpress API: Display Formats

jarmes — Sun, 13 Dec 2009 04:24:03 +0000

You have learned about all of the functions. You understand the data formats. What could possibly be left before mastering the WorkXpress API? Display formats is the answer.

Display formats allow you to pull out data in different formats. For example, instead of pulling a file field as XML (stored value) or just the filename (text value), you could get the download URL. When using display formats, the format type must be set to "text". Not all Fields have display formats, while others have several. Many of the available formats match the available parts for multi-part fields. For more information on these parts, see my previous post on data formats.

Address

The Address Field Type exposes a number of display formats to match the available parts of the field.

Type
Street
Street2
Street3
City
State
ZipCode
Country

These formats can be combined to create you own format. For example, let's say you want to display only the city, state and zip code of the address. Your format string would look as follows:
$format = 'City, State ZipCode';
You can even add your own text to the string, just make sure not to use any of the format parts in your custom text (display formats are case sensitive).
$format = 'You live in City, State Country';

// since display formats are case sensitive, you could also do something like the following $format = 'This client hails from the city of City';

Currency

Currency Fields usually return the currency symbol ($) when using the text only version. Using the NumberOnly format allows you to pull the value without the currency symbol (ie. "3.12" instead of "$3.12"). You can get the same result from using the stored format type instead of text.

Phone Number

Phone Number Fields are similar to Address Fields. The display formats for Phone Number Fields match the available parts.

Type
CountryCode
AreaCode
Prefix
LineNumber
Extension

Select - Select One

Select - Select One Fields provide display formats that allow access to some of their special features. No display format will return the title of the currently selected Select Option.

AltTitle: Alternate title of the currently selected Select Option.
WithOther: Title of the currently selected Select Option as well as the value of the "Other" Field for the Select Option (if any).
OtherOnly: Returns only the value of the "Other" Field of the currently selected Select Option (if any).

Check Box

Check Box Fields provide a few different formats to handle their unique on/off nature. Most of your requirements for this Field Type can be handled using the stored format type.

Checked: Returns the values "CHECKED" or "UNCHECKED".
FieldLabel: Either the Field's label or empty.
WithOther: Returns the same as the Checked display format followed by a hyphen and the value of the "Other" Field for the current state (if any).
OtherOnly: Returns only the value of the "Other" Field for the current state (if any).

Date and Date Time

Date and Date Time Fields provide display formats that can be useful for displaying their values in different formats. Many of these formats correspond to the formats provided by PHP's date function.

AMPMLowercase: Lowercase ante meridiem or post meridiem value.
AMPMUppercase: Uppercase ante meridiem or port meridiem value.
DayOfMonth: Day of the month without leading zeros.
DayOfMonthSuffix: Two character English ordinal day of the month (ie. st for 1st or th for 13th).
DayOfMonthLeadingZero: Two digit day of the month with leading zeros.
DayOfWeek: Full day of the week title (ie. Monday).
DayOfWeekAbbreviated: Three character day of the week title (ie. Mon).
DayOfWeekNumber: ISO-8601 numeric day of the week.
DayOfYear: Day of the year starting with zero.
Hour: 12-hour formatted hour without leading zero.
Hour24: 24-hour formatted hour without leading zero.
Hour24LeadingZero: 24-hour formatted hour with leading zero.
HourLeadingZero: 12-hour formatted hour with leading zero.
Minute: Two digit minutes with leading zeros.
MonthName: Full month title (ie. January).
MonthNameAbbreviated: Three character month title (ie. Jan).
MonthOfYear: Numeric representation of the month without leading zero.
MonthOfYearLeadingZero: Numeric representation of the month with leading zero.
Second: Two digit seconds with leading zero.
Timestamp: Seconds since the Unix epoch (January 1, 1970 00:00:00 GMT).
WeekOfYear: ISO-8601 numeric week number of the year.
Year: Four digit year.
YearShort: Two digit year.

File

File Fields can be difficult to deal with. Display formats are here to help. Using the display formats below, File Fields can be much easier to deal with.

DownloadURL: The URL that can be used to download the file. If the Field is configured to be private, this URL will require a user to be logged in.
Filename: Name of the file, including the extension.
FileSize: Size of the file in bytes.
Height: If the file is an image, this will return the height of the image in pixels.
Image: If the file is an image, this will return the image tag that can be used in an HTML document. The image must be public for this to be used outside of the Application.
MimeType: The file's mime-type (ie.image/png).
Thumbnail: Similar to the Image display format, but the src attribute will be pointed at the thumbnail.
ThumbnailURL: If the file is an image, this will return the same as the DownloadURL display format but for the thumbnail image.
Width: If the file is an image, this will return the width of the image in pixels.

Social Security

Social Security Fields provide only a single display format part. By using the LastFour format, you can retrieve only the last four digits of a social security number. With no display format, this Field Type will return the value as "***-**-####".

Now You're Ready

That's all folks. You have everything you need to master the WorkXpress API. The API opens up a lot of possibilities for you and your application. Current uses of the API include integrating with FedEx shipping services, data imports with HarrisData and administration of FTP servers. Once you have had a chance to explore the power of the API, come back here and let me know how you used it. As always, if you have any questions, leave a comment below.

Tags:

External Links and GeSHi Filter

jarmes — Sat, 05 Dec 2009 02:42:09 +0000

On my site I use the External links to add the image next to any external links. I also use the GeSHi Filter module for syntax highlighting. These two modules together were causing some undesirable effects.

The GeSHi Filter module adds links to the PHP manual entry for functions. Because this is an external link, it receives the image from above. This doesn't look quite right:

So what did I do about it? I added the following lines to me themes CSS file (sandbox.css for those who were wondering):

div.geshifilter span.ext {
  background: none;
  padding-right:0;
}

As you can see by the following screen shot, the icon no longer appears in my code:

I hope this was able to help somebody else out

Tags:

CSS

Drupal

Using the WorkXpress API: Data Formats

jarmes — Tue, 27 Oct 2009 01:23:30 +0000

Now that you know how to use the WorkXpress API, it's time to learn about some more advanced concepts. Data formats define how Field values are stored within WorkXpress. These values can be useful for finding out more information about certain values, and will need to be used when storing data into certain Field Types.

The WorkXpress Engine tries hard to store data in simple, easy, logical formats. Below is a description of some of the less straightforward Field Types, and what format their data is expected in.

Item Pickers

Item Picker Fields store references to other Items. They can be used to manage Relationships, display links and other Fields attached to the referenced Item or to simply reference the Item in Actions.

Item Pickers are split into two primary types: single and multi. Single Item Pickers store a reference to only one Item at a time. Multi Item Pickers can store a reference to multiple Items at a time. Each of these types of Item Pickers is then broken down into Select Item Pickers and Pick Item Pickers. Select Item Pickers display as either a single select box or a multi-select Field. Single and Multi Item Pickers have slightly different stored values; however, there is no difference in the stored value of Select Item Pickers and Pick Item Pickers.

Single Item Pickers store their value as follows:

<ItemTypeId>|<ItemId> (ex. a1325|u15)

Multi Item Pickers store their value as follows:

<ItemTypeId>|<ItemId>,<ItemTypeId>|<ItemId>,... (ex. a1325|u15,a1325|u28,a1325|u193)

Selects

Select Fields are very similar to Item Picker Fields. They are split into single and multi selects. Select also store Items; however, they only store Items of type "Select Option" and these Items are pre-defined and related to the Field. The Item Type id of Select Options is e11, so all Select Field values will be prefixed with this id.

Single Selects store their value as follows:

e11|<ItemId> (ex. e11|a32859)

Multi Selects store their value as follows:

e11|<ItemId>,e11|<ItemId>,... (ex. e11|a49462,e11|a28957,e11|a1337)

Select Fields can also be set by passing in the title or alt title of the Select Option(s). For example let's say you the two options below available for a Single Select:

Select Options

You could set this Field to the value "Open" by passing in either "Open" or "O". For Multi Selects, you can mix and match the values. If the previous example was a Multi Select Field, you could set it by passing in "Open,C" or even "O,e11|a295456".

Check Box

Check box Fields work like boolean values. When a check box Field is "on" or "true", the stored value will be 1. Any non-empty value may be passed in to set a check box to "on". When a check box Field is "off" or "false", the stored value will be empty. An empty value should be passed in to set a check box to "off".

Date, Time & Date Time

Date, Time and Date Time Fields are all stored as a Unix time stamp. A Unix time stamp represents the number of seconds since the Unix epoch (January 1, 1970), excluding leap seconds. This makes adding and subtracting time a simple arithmetic operation. PHP can easily handle and manipulate these values using its built in date functions.

// convert a standard date into a unix time stamp and back again
$value = '01/29/1985';
$timestamp = strtotime($date);
$formatted = date('m/d/Y');

// convert a date and time value into a unix time stamp and back again
$value = '01/29/1985 11:35am';
$timestamp = strtotime($date);
$formatted = date('m/d/Y h:ia');

// convert a time only value into a unix time stamp and back again
$value = '11:35am';
$timestamp = strtotime('January 1, 1970 '.$time);
$formatted = date('h:ia');

File Attachment

File Attachment Fields are what WorkXpress refers to as a multi-part Field. Multi-part Fields are stored as XML so that each part can be referenced separately. There are two different ways of setting a File Attachment Field though the API:

Pass in XML with the encoded_file and filename parts set
Pass in XML with the download_url set

To base 64 encode a file in PHP, use the code below:

$filename = '/home/jarmes/example.png';
$binary_data = file_get_contents($filename);
$encoded_file = base64_encode($binary_data);

// this could also be done on one line
$encoded_file = base64_encode(file_get_contents('/home/jarmes/example.png'));

The XML for a File Attachment Field should be structured using the below definition.

Element

Description

/multi_part_field

The root node for all multi-part Fields.

/multi_part_field/part

Defines the value for a single part of the Field.
Attributes:

Name	Type	Description
id	string	Id of the current part. Valid values for File Attachment Fields include: filename: The filename to be given to the file when it is saved on the WorkXpress file system. mime_type: The mime-type of the file (ie. image/jpeg) size: The file's size in bytes encoded_file: The base 64 encoded binary data of the file download_url: When retrieving a stored value, this will have a URL that can be used to download the file. If the Field is not configured to allow public files, this URL will require a valid login to the application. When setting a Field, this value may be set to a URL that WorkXpress should use to retrieve the file.

Example:

<multi_part_field>
  <part id="filename">example.png</part>
  <part id="mime_type">image/png</part>
  <part id="size">364544</part>
  <part id="encoded_file">$encoded_file</part>
  <part id="download_url">http://www.example.com/example.png</part>
</multi_part_field>

Address

Address Fields are also multi-part. Address Fields have two different types: US and International. If the "type" part of an address value is not set, it is assumed to be US.

The XML for an Address Field should be structured using the below definition.

Element

Description

/multi_part_field

The root node for all multi-part Fields.

/multi_part_field/part

Defines the value for a single part of the Field.
Attributes:

Name	Type	Description
id	string	Id of the current part. Valid values for Address Fields include: street: The first street value. street2: The second street value. street: The third street value (International values only). city: The city value. state: The state value. International values may have up to three characters. US values must have exactly two characters. zip_code: The postal code value. Should be five character numeric for US values. country: The country value. This value is required for International values. United States will be used for US values regardless of any value passed in. Should be the full country name (ie. Canada, South Africa) or the ISO 3166-1 alpha-3 formatted country code. type: Should be either International or United States. sort_value: Defines which street part will be used when sorting this value. Valid values include street, street2, and street3. This part is required for International values. US values will always use street.

Example:

<multi_part_field>
  <part id="street">Ostvorstadt</part>
  <part id="street2">Hauptstraße 5</part>
  <part id="street3"></part>
  <part id="city">Musterstadt</part>
  <part id="state"></part>
  <part id="zip_code">01234</part>
  <part id="country">Germany</part>
  <part id="type">International</part>
  <part id="sort_value">street2</part>
</multi_part_field>

Phone Number

Phone Numer Fields are the last of the multi-part Fields. Like Address Fields, Phone Numbers can have two types: International and US. If the "type" part is not defined, it is assumed to be US.

The XML for a Phone Number Field should be structured using the below definition.

Element

Description

/multi_part_field

The root node for all multi-part Fields.

/multi_part_field/part

Defines the value for a single part of the Field.
Attributes:

Name	Type	Description
id	string	Id of the current part. Valid values for Phone Number Fields include: area_code: The area code value. Should be three digits for US values and up to five alpha-numeric characters for International values. prefix: The first three digits of a US phone number (US values only). line_numer: The last four digits of a US phone number. For International values, this is used for the remainder of the phone number (everything after the area code). extension: The optional extension value. Phone Number Fields can be set up to not display this value even if it has been set. country_code: The country calling code for International values. This will always be set to 1 for US values. type: Should be either International or United States.

Example:

<multi_part_field>
  <part id="area_code">717</part>
  <part id="prefix">609</part>
  <part id="line_number">0029</part>
  <part id="extension">123</part>
  <part id="country_code">1</part>
  <part id="type">United States</part>
</multi_part_field>

That's it for the WorkXpress Data Formats. All other Fields use simple storage types (ie. Currency stores as a number, Short Text stores as text). If you have any questions about these data formats, please feel free to leave a comment below. My next and final post on the WorkXpress API will cover display formats.

Tags:

Using the WorkXpress API: ExecuteAction

jarmes — Tue, 27 Oct 2009 00:18:21 +0000

Earlier I introduced you to the WorkXpress API. If you have not read it already you should do so before reading this post. Once you have a basic understanding of what it is and how it works, it's time to start diving into the API.

This post will cover how to run specfic Actions on specific Items. You can find the id of an Action at the end of its description in the Event Manager (see below). Like the other functions, you can make many ExecuteAction requests in one call using data sets.

WorkXpress Event Manager

Request XML

First, let's get an understanding of how the request XML should be formed.

Element

Description

/wxRequest

The root node for all request documents.

/wxRequest/dataSet

Contains a single ExecuteAction request. You may have as many data sets as you would like.
Attributes:

Name	Type	Description
reference	string	An identifier that will be returned in the reponse document to distinguish between different data sets. If this attribute is left blank, a random string will be generated.

/wxRequest/dataSet/
items

Root node for the items that the Action(s) should be run on.

/wxRequest/dataSet/
items/item

A single item to execute the action on. There is no limit to the number of item nodes allowed in a data set.
Attributes:

Name	Type	Description
itemId	string	The item id of the item to execute the action on. Should be in the format u# (ie. u123).

/wxRequest/dataSet/
items/map

The root node for a map definition.

/wxRequest/dataSet/
items/map/definition

The actual definition for a map. The map XML must have its HTML entities encoded.

/wxRequest/dataSet/
actions

Root node for the Actions to be executed.

/wxRequest/dataSet/
actions/action

A single Action to be executed on the Items defined above. There is no limit to the number of action nodes allowed in a data set.
Attributes:

Name	Type	Description
actionId	string	Id of a single Action to run. Should be in the format a# (ie. a123).

Response XML

Now let's get an understanding of how the response XML will be formed.

Element

Description

/wxResponse

The root node for all response documents.

/wxRequest/callStatus

The status of the SOAP call as it was processed by WorkXpress.
Attributes:

Name	Type	Description
status	string	The call's status. Values include success and failure.

/wxResponse/compatibilityLevel

The version of the API that was used to process the request.

/wxRequest/dataSet

One data set is returned for each data set in the request document.
Attributes:

Name	Type	Description
reference	string	The identifier that was assigned to the data set in the request.

/wxRequest/dataSet/
item

Defines an item that the Action(s) was executed on. One item node is returned for each item that an Action was run on.
Attributes:

Name	Type	Description
itemId	string	Id of the item, in the format u# (ie. u123).

Examples

Below is an example of a basic ExecuteAction request document:

<wxrequest>
  <dataset reference="accounts">
    <items>
      <item itemid="u3541">
      <item itemid="u511">
    </item></item></items>
    <actions>
      <action actionid="a314558">
    </action></actions>
  </dataset>
</wxrequest>

Below is the corresponding response document for the above example:

<wxresponse>
  <callstatus status="success">
    <compatibilitylevel>1</compatibilitylevel>
    <dataset reference="accounts">
      <item itemid="u3541"></item>
      <item itemid="u511"></item>
    </dataset>
  </callstatus>
</wxresponse>

If you have any questions or would like assistance making some ExecuteAction requests of your own, please feel free to comment below. My next post will be on some more advanced concepts such as display formats and stored values.

Tags:

Using the WorkXpress API: UpdateItem

jarmes — Thu, 22 Oct 2009 00:17:51 +0000

This post will cover how to update existing Items in a WorkXpress application using the UpdateItem API function. UpdateItem allows you to set Fields, create Relationships and recycle and delete Items & Relationships. Like the other functions, you can make many UpdateItem requests in one call using data sets.

Request XML

First, let's get an understanding of how the request XML should be formed.

Element

Description

/wxRequest

The root node for all request documents.

/wxRequest/dataSet

Contains a single UpdateItem request. You may have as many data sets as you would like.
Attributes:

Name	Type	Description
reference	string	An identifier that will be returned in the request document to distinguish between different data sets. If this attribute is left blank, a random string will be generated.
action	string	The operation to be performed on the requested action delete: Once an Item has been deleted from WorkXpress, it can only be retrieved by restoring an earlier backup. You should only delete Items if you know for sure that you will not need it in the future. Deleting an Item will also delete any Relationships to other Items. recycle: Recycled Items can be restored using the restore action (see below). When an Item is recycled, it will no longer be returned in search results; this includes (but is not limited to) Actions and List Layouts. All Relationships to other Items will also be recycled. restore: Restoring a recycled Item will make it available to searchng again. Restoring an Item will also restore any recycled Relations to other Items. update: Updates an existing Item.

/wxRequest/dataSet/
items

Root node for the items that should be retrieved.

/wxRequest/dataSet/
items/item

A single item to be updated. There is no limit to the number of item nodes allowed in a data set.
Attributes:

Name	Type	Description
itemId	string	The item id of the item to update from. Should be in the format u# (ie. u123).

/wxRequest/dataSet/
items/map

The root node for a map definition.

/wxRequest/dataSet/
items/map/definition

The actual definition for a map. The map XML must have its HTML entities encoded.

/wxRequest/dataSet/fields

Root node for any fields that should be updated on the items that were found in the items node.

/wxRequest/dataSet/
fields/field

A single field to update on the Item.
Attributes:

Name	Type	Description
fieldId	string	Id of the field to set. Should be in the format a# (ie. a123).

/wxRequest/dataSet/
fields/field/
value

Value to set into the field.

/wxRequest/dataSet/
relations

Root node for relations that should be added or updated with the current item.

/wxRequest/dataSet/
relations/relation

Defines a single relation to be added or updated. If the action is not "add", the attributes will be used to look up an existing relation. Attributes:

Name	Type	Description
action	string	The action to perform for this relation. add: Creates a new relationship using the other attributes to define the new relationship. delete: Similar to items, deleted relationships are completely removed from WorkXpress and can only be retrieved by restoring a previous backup. recycle: Recycled relationships are not removed from WorkXpress and can be restored using the restore action. restore: Restores a relationship that was previously recycled. update: Updates an existing relation.
oppositeItemId	string	Id of the item on the opposite side of the relation. For example, if the item being updated is an account and you want to relate it to a contact (or update an existing relationship to a contact), this would be the id of the contact. Should be in the format u# (ie. u123).
reference	string	An identifier that will be returned with the response to identify each relationship.
relationType	string	Relation type of the relationship. Should be in the format a# (ie. a123).
startingSide	string	Defines which side of the relation that the item defined above should be on. Valid values are base and target.

/wxRequest/dataSet/
relations/relation/
fields

Root node for the fields that should be set on the relationship.

/wxRequest/dataSet/
relations/relation/
fields/field

A single field to be set on the relationship.
Attributes:

Name	Type	Description
fieldId	string	Id of the field to set. Should be in the format a# (ie. a123).

/wxRequest/dataSet/
relations/relation/
fields/field/
value

Value to set into the field.

Response XML

Now let's get an understanding of how the response XML will be formed.

Element

Description

/wxResponse

The root node for all response documents.

/wxRequest/callStatus

The status of the SOAP call as it was processed by WorkXpress.
Attributes:

Name	Type	Description
status	string	The call's status. Values include success and failure.

/wxResponse/compatibilityLevel

The version of the API that was used to process the request.

/wxRequest/dataSet

One data set is returned for each data set in the request document.
Attributes:

Name	Type	Description
reference	string	The identifier that was assigned to the data set in the request.

/wxRequest/dataSet/
item

Defines an item that was updated. One item node is returned for each item that was updated by WorkXpress.
Attributes:

Name	Type	Description
itemId	string	Id of the item that was updated, in the format u# (ie. u123).

/wxRequest/dataSet/
item/relation

Defines a relationship that was added or updated. Returns one relation node for each relationship from the item that was added or updated by WorkXpress. Attributes:

Name	Type	Description
reference	string	The identifier of the relation that was assigned to the relation in the request.
relationId	string	Id of the relation that was added or updated, in the format u# (ie. u123).

Examples

Below is an example of a basic UpdateItem request document:

<wxrequest>
  <dataset action="update" reference="account_update">
    <items>
      <item itemid="u7563"></item>
    </items>
    <fields>
      <field fieldid="a66969">
        <value>WorkXpress</value>
      </field>
    </fields>
    <relations>
      <relation action="update" oppositeitemid="u7436" reference="account_to_contact" relationtype="a36495" startingside="base">
        <fields>
          <field fieldid="a36498">
            <value>Intern</value>
          </field>
          <field fieldid="a36513">
            <value>foo@example.com</value>
          </field>
        </fields>
      </relation>
    </relations>
  </dataset>
  <dataset action="recycle" reference="account_recycle">
    <items>
      <map>
        <definition>
          <?xml version="1.0" encoding="UTF-8"?>
          <wxQuery
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="wxQuery.xsd"
            id="root">
            <data for="root">
              <item/>
            </data>
            <startingTypes>
              <startingType>a5543</startingType>
            </startingTypes>
            <paramGroup id="wx4adfb3c227d12">
              <join>and</join>
              <fieldSearch id="wx4adfb3d738a91">
                <fieldId>a39651</fieldId>
                <operator>fieldLessThanEqualTo</operator>
                <input>
                  &lt;?xml version="1.0"?&gt;
                  &lt;search_value&gt;
                    &lt;first_value&gt;
                      -1 years
                    &lt;/first_value&gt;
                  &lt;/search_value&gt;
                </input>
              </fieldSearch>
            </paramGroup>
          </wxQuery>
        </definition>
      </map>
    </items>
  </dataset>
</wxrequest>

Below is the corresponding response document for the above example:

<wxresponse>
  <callstatus status="success"></callstatus>
  <compatibilitylevel>1</compatibilitylevel>
  <dataset reference="account_update">
    <item itemid="u7563">
      <relation reference="account_to_contact" relationid="u7564"></relation>
    </item>
  </dataset>
  <dataset reference="account_recycle">
    <item itemid="u1782"></item>
  </dataset>
</wxresponse>

If you have any questions or would like assistance making some UpdateItem requests of your own, please feel free to comment below. My next post will be on how to use the ExecuteAction request.

Tags:

JamesArmes.com

Barcamp Harrisburg: Setting up shop with Drupal Commerce

Resources

Additional modules used in demonstration

Other

The New Jimmy's Sandbox

Your Thoughts

Jimmy's Fridge

Drupal 6 Performance on GoDaddy

Drupal's Performance Settings

Caches

CSS/JavaScript Optimizations

Google Analytics Optimizations

JavaScript Compression

What Performance Tips Do You Have?

Simple Tips For Repsonding To A Web Developer Job Posting

1. Use a professional email address

2. Use a professional yet personal greeting

3. Use proper capitalization

Example 1:

Example 2:

4. Add some descriptions to your examples

Example 3:

Example 4:

5. Use complete sentences

Example 5:

6. Use correct grammar

Example 6:

Example 7:

Example 8:

Your turn

Using the WorkXpress API: Display Formats

Address

Currency

Phone Number

Select - Select One

Check Box

Date and Date Time

File

Social Security

Now You're Ready

External Links and GeSHi Filter

Using the WorkXpress API: Data Formats

Item Pickers

Selects

Check Box

Date, Time & Date Time

File Attachment

Address

Phone Number

Using the WorkXpress API: ExecuteAction

Request XML

Response XML

Examples

Using the WorkXpress API: UpdateItem

Request XML

Response XML

Examples