Using the WorkXpress API: ExecuteAction

25 Oct 2009 | API, PHP, SOAP, Web Services, WorkXpress

WorkXpress 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
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:
  • reference (string): An identifier that will be returned in the response 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 numbe of item nodes allowed in a data set.

Attributes:
  • 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:
  • 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:
  • 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:
  • 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:
  • 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>
      <item itemid="u511"></item>
    </items>
    <actions>
      <action actionid="a314558"></action>
    </actions>
  </dataset>
</wxrequest>

Below is the corresponding response document for the above example:

<wxresponse>
  <callstatus status="success"></callstatus>
  <compatibilitylevel>1</compatibilitylevel>
  <dataset reference="accounts">
    <item itemid="u3541"></item>
    <item itemid="u511"></item>
  </dataset>
</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.

comments powered by Disqus

Older · View Archive (34)

Using the WorkXpress API: UpdateItem

WorkXpress 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.

Newer

Using the WorkXpress API: Data Formats

WorkXpress 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.