| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
 Previous |
 Next |
| Agile Product Lifecycle Management Web Services Guide Release 9.3.6 E71166-01 |
|
Previous |
Next |
This chapter describes how to work with the web services in the Agile Recipe and Material Workspace (RMW) application and provides sample code snippets.
RMW searches can be simple or advanced searches, with multiple criteria. RMW search operation lets you perform searches and sorting in one go.
This feature allows the user to provide the operator type along with the criteria. Only operators that are supported by the RMW UI are supported in the enhanced cfmXML.
Operators that are supported by enhanced cfmXML are:
OP_DEFAULT
OP_MATCHES
OP_BETWEEN
The Operators are supported with the following modification to cfmXML
Optional Values element inside Attribute element. This will contain n number of Values element
Optional operator attribute in Attribute element with the following possible values
Example: Searching by user using the OP_DEFAULT operator
<SearchCriteria id="1">
<SearchName>AdminUser</SearchName>
<CategoryName>User</CategoryName>
<CategoryDBName>D_PPL_USER</CategoryDBName>
<ViewName/>
<Attribute name="User ID" operator="OP_DEFAULT">
<Value dataType="Text">Administrator</Value>
<UnitOfMeasure/>
</Attribute>
</SearchCriteria>
Example: Searching between dates using the OP_BETWEEN operator
<SearchCriteria id="1">
<CategoryName>User</CategoryName>
<CategoryDBName>D_PPL_USER</CategoryDBName>
<ViewName/>
<Attribute name="Created Date" operator="OP_BETWEEN">
<Value dataType=""/>
<Values>
<Value GMTDateTime="1156863952000" dataType="Date">08/29/2006</Value>
<Value GMTDateTime="1156863952000" dataType="Date">08/29/2006</Value>
</Values>
<UnitOfMeasure/>
<Format>MM/dd/yyyy</Format>
</Attribute>
</SearchCriteria>
This feature has an impact on the order of the results that are displayed. The sorting criteria specified in request xml will be considered and displayed accordingly. The user can specify the field name that has to sort on and the order that must be displayed in ascending or descending order.
Sorting using more than one field name is supported; in which case the order value will be considered to resolve the sorting order.
The sorting feature is supported with the following changes to CfmXML:
Optional SortGroup element containing 'n' number of Attribute elements.
Optional order attribute in Attribute element which contains the order of sorting. If order is not specified for the attribute then actual order will be considered.
Optional ascending attribute in Attribute element with yes/no possible values. Default value is yes.
Example: Searching with sorting
<SearchCriteria id="1">
<CategoryName>User</CategoryName>
<CategoryDBName>D_PPL_USER</CategoryDBName>
<ViewName/>
<Attribute name="User ID">
<Value dataType=""/>
<Values>
<Value dataType="Text">Administrator</Value>
<Value dataType="Text">System</Value>
<Value dataType="Text">boprocqc</Value>
</Values>
<UnitOfMeasure/>
</Attribute>
<SortGroup>
<Attribute ascending="yes" name="Is Active" order="1">
<Value dataType="Text"/>
<UnitOfMeasure/>
</Attribute>
<Attribute ascending="no" name="First Name" order="2">
<Value dataType="Text"/>
<UnitOfMeasure/>
</Attribute>
</SortGroup>
</SearchCriteria>
This features allows the user to search by providing multiple values for search criteria. This considers as ‗In clause' and the results will include all the records which meets the values in the list.
<SearchCriteria id="1">
<CategoryName>User</CategoryName>
<CategoryDBName>D_PPL_USER</CategoryDBName>
<ViewName/>
<Attribute name="Work Phone">
<Value dataType=""/>
<Values>
<Value dataType="Phone">14001</Value>
<Value dataType="Phone">91-5643728990</Value>
<Value dataType="Phone">91-5643728990</Value>
</Values>
<UnitOfMeasure> </UnitOfMeasure>
<Format>dd-MM-yyyy</Format>
</Attribute>
<SortGroup>
<Attribute ascending="no" name="Work Phone" order="1">
<Value dataType="Text"/>
<UnitOfMeasure/>
</Attribute>
</SortGroup>
</SearchCriteria>
This is a generic edit Web service. Using this, you can perform edit operation on any category by providing the payload value in cfmXML format.
<Object operation="D">
<CategoryName>Application Setup</CategoryName>
<CategoryDBName>D_INT_APPLICATION_SETUP</CategoryDBName>
<ViewName>DEFAULT</ViewName>
<ObjectKey>
<Attribute name="Application Name">
<Value dataType="Basic Text">TestApplication</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail/>
</Object>
Input Type
You can specify whether the editing operation is for Insert or Update or Delete. It is specified using <Object operation="I"> or <Object operation="U"> or <Object operation="D">.
Example: Inserting a User data
<Payload>
<Object operation="I">
<CategoryName>WSEditTest</CategoryName>
<CategoryDBName>WSEditTest</CategoryDBName>
<ViewName/>
<CustomInfo/>
<ObjectKey>
<Attribute name="UserId">
<Value dataType="Integer">3</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Experience">
<Value dataType="Integer">3</Value>
<UnitOfMeasure/>
</Attribute>
<Attribute name="Rank">
<Value dataType="Integer">3</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectDetail>
</Object>
</Payload>
Example: Updating a user data
|
Note: Before invoking the Update Input XML service, you must invoke the Insert operation. |
<Payload>
<Object operation="U">
<CategoryName>WSEditTest</CategoryName>
<CategoryDBName>WSEditTest</CategoryDBName>
<ObjectKey>
<Attribute name="Experience">
<Value dataType="Intger">4</Value>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Rank">
<Value dataType="Integer">1</Value>
</Attribute>
</ObjectDetail>
</Object>
</Payload>
Example: Inserting and updating a user data
<Payload>
<Object operation="I">
<CategoryName>Application Setup</CategoryName>
<CategoryDBName>D_INT_APPLICATION_SETUP</CategoryDBName>
<ViewName>DEFAULT</ViewName>
<ObjectKey>
<Attribute name="Application Name">
<Value dataType="Basic Text">App Insert Test</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Application User Id">
<Value dataType="Basic Text">App Insert Test User Id</Value>
<UnitOfMeasure/>
</Attribute>
<Attribute name="Inbound XSL">
<Value dataType="Basic Text">App Insert Test Inbound XSL</Value>
<UnitOfMeasure/>
</Attribute>
<Attribute name="Outbound XSL">
<Value dataType="Basic Text">App Insert Test Outbound XSL</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectDetail>
</Object>
<Object operation="U">
<CategoryName>Application Setup</CategoryName>
<CategoryDBName>D_INT_APPLICATION_SETUP</CategoryDBName>
<ViewName>DEFAULT</ViewName>
<ObjectKey>
<Attribute name="Application Name">
<Value dataType="Basic Text">Test App Name</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Application User Id">
<Value dataType="Basic Text">Updated User Id</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectDetail>
</Object>
</Payload>
This is a generic web service to process any Business Object (BO), configured in the system, using Web Service. Operations such as Add/Modify/Delete can be performed on Business Object by just invoking this web service with BO details in the form of cfmXML.
BO web service processes multiple BOs. Hence, there is a standard mechanism to report errors and warning, if any during the processing of BOs.
Response code: 300 - This response code indicates failure of processBO operation with errors, warnings and validations as part of response message.
Response code: 301 - This response code indicates failure of processBO operation and errors, warnings and validations are contained in the response message.
Response code: 500 - This response code indicates success of processBO operation.
Example: Inserting a new Application
<Payload>
<Object>
<CategoryName/>
<CategoryDBName/>
<ObjectKey/>
<ObjectDetail/>
</Object>
<ObjectGroup isBO="Yes" name="Application">
<BOActions>
<BOAction>New</BOAction>
</BOActions>
<Object name="BORoot">
<CategoryName>Application Setup</CategoryName>
<CategoryDBName>D_INT_APPLICATION_SETUP</CategoryDBName>
<ViewName/>
<CustomInfo/>
<ObjectKey>
<Attribute name="Application Name">
<Value dataType="Text">JUNIT_BO_WS_Test_Application_041</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Inbound XSL">
<Value dataType="Text">inbound</Value>
<UnitOfMeasure/>
</Attribute>
<Attribute name="Outbound XSL">
<Value dataType="Text">outbound</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectDetail>
</Object>
</ObjectGroup>
<ObjectGroup isBO="Yes" name="Application">
<BOActions>
<BOAction>New</BOAction>
</BOActions>
<Object name="BORoot">
<CategoryName>Application Setup</CategoryName>
<CategoryDBName>D_INT_APPLICATION_SETUP</CategoryDBName>
<ViewName/>
<CustomInfo/>
<ObjectKey>
<Attribute name="Application Name">
<Value dataType="Text">JUNIT_BO_WS_Test_Application_002</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail>
<Attribute name="Inbound XSL">
<Value dataType="Text">inbound</Value>
<UnitOfMeasure/>
</Attribute>
<Attribute name="Outbound XSL">
<Value dataType="Text">outbound</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectDetail>
</Object>
</ObjectGroup>
</Payload>
Example: Removing a User
<Payload>
<Object>
<CategoryName/>
<CategoryDBName/>
<ObjectKey/>
<ObjectDetail/>
</Object>
<ObjectGroup isBO="Yes" name="User">
<BOActions>
<BOAction>Remove</BOAction>
</BOActions>
<Object name="BORoot">
<CategoryName>User</CategoryName>
<CategoryDBName>D_PPL_USER</CategoryDBName>
<ViewName>DEFAULT</ViewName>
<ObjectKey>
<ObjectID>785538</ObjectID>
<Attribute name="User ID">
<Value dataType="Basic Text">Administrator_Test01</Value>
<UnitOfMeasure/>
</Attribute>
</ObjectKey>
<ObjectDetail/>
</Object>
</ObjectGroup>
</Payload>
cfmXML is a proprietary XML standard developed for integrating web services in the Agile RMW application. It is used for communication within the RMW system, and between RMW and other applications.
Details of tags used in cfmXML are explained below with the help of few sample messages.
<?xml version="2.0" encoding="UTF-8"?> <cfmXML>
<LoginInfo>
<UserName>String</UserName>
<Password>String</Password>
<Database>String</Database>
<AppUserName>String</AppUserName>
<AppPassword>String</AppPassword>
</LoginInfo>
<SessionInfo logout="true">
<UserName>String</UserName> <SessionID>String</SessionID> </SessionInfo>
<PageInfo>
<PageName>String</PageName>
<ReturnURL>
<URL>String</URL>
</ReturnURL>
</PageInfo>
<Response>
<ResponseCode>String</ResponseCode>
<ResponseMessage>String</ResponseMessage>
<SessionID>String</SessionID>
<RedirectURL>String</RedirectURL>
</Response>
<SearchCriteria/>
<SearchInfo/>
<Payload/>
<AdditionalInfo/>
</cfmXML>
This table contains user authentication information. User ID and Password are used for authenticating the user.
| cfmXML tag | Outbound Message | Inbound Message |
|---|---|---|
| <UserName> | User ID of the current user logged in to the RMW system. | User ID of the user-sending message. Value must be specified. Used to login the specified user in the RMW database. |
| <Password> | The RMW database login password for the current user. | The value is specified for login purpose. If the value is not specified, it returns error. |
| <Database> | Name of the database to connect the external application. This will usually be blank for an outgoing message. | Name of the database to which the RMW need to connect to in order to serve the request. |
| <AppUserName> | Name of user in application setup table for a particular application | Name of user in application setup table for a particular application |
| <AppPassword> | Password of user in application setup table for a particular application | Password of user in application setup table for a particular application |
This table contains session ID of a successfully created session. Once a user is authenticated, session info can be used for subsequent calls to connect to an earlier created session.
| cfmXML tag | Outbound Message | Inbound Message |
| <SessionInfo logout> | It contains the current RMW session information. This will be useful if the invoked Web service needs to connect back to the RMW application to get some more data. | It denotes the session ID of the previous RMW session to be reused. If the specified session ID has expired, a new session is created for the user. Attribute logout contains information on whether to continue the session or end the session. If it is True, end the session or else continue the session. |
| <UserName> | User ID of the current logged in user. | It is the user login ID for the session to be reused. |
| <SessionID> | Session ID of the current user. | Contains session ID for the session to be reused. |
This table contains the information about the page to integrate with for UI integration.
| cfmXML tag | Outbound Message | Inbound Message |
| <PageName> | Not Used | Contains name of the page, which must be launched when control is transferred to the RMW application. |
| <URL> | This is the return URL picked up from the Application Setup class for the application to which punch-out is being done. If there is no value specified in the Setup class, URL of the current RMW page is sent as the return URL | If Return URL is present, cfmXML payload is sent to the Return URL and user is redirected to the ReturnURL. |
This is the response code and message for the requested operation.
| cfmXML tag | Outbound Message | Inbound Message |
| <ResponseCode> | Contains the Response code generated by the external application. | Contains the Response code generated by the RMW System. 500 for success and 300 for error. |
| <ResponseMessage> | Contains the response message. | Contains the response message for the corresponding code. |
| <SessionID> | Contains session ID for the session in use. | Contains session ID for the RMW System session that was created or re-used for the request. |
| <RedirectURL> | Contains the external application URL to which the RMW System user must be redirected to for the UI integration. | Contains the RMW System URL to which user must be redirected to for UI integration. |
<?xml version="2.0" encoding="UTF-8"?>
<cfmXML>
<LoginInfo/>
<SessionInfo/>
<PageInfo/>
<ScreenContext/>
<Response/>
<SearchCriteria isPrimary="yes" id="0" execute="yes">
<CategoryName>String</CategoryName>
<CategoryDBName>String</CategoryDBName>
<ViewName>String</ViewName>
<Attribute name="String">
<Value dataType="String" asEnteredValue="String">String</Value>
<UnitOfMeasure>String</UnitOfMeasure>
</Attribute>
<Relationship type="inbound" refid="String" name="String" resolve="yes">
<CategoryName>String</CategoryName>
<CategoryDBName>String</CategoryDBName>
<ObjectKey>
<ObjectID>String</ObjectID>
<Attribute name="String">
<Value dataType="String" asEnteredValue="String">String</Value>
<UnitOfMeasure>String</UnitOfMeasure>
</Attribute>
<Relationship type="inbound" refid="String" name="String" resolve="yes">
<CategoryName>String</CategoryName>
<CategoryDBName>String</CategoryDBName>
<ObjectKey>
<ObjectID>String</ObjectID>
<Attribute name="String">
<Value dataType="String" asEnteredValue="String">String</Value>
<UnitOfMeasure>String</UnitOfMeasure>
</Attribute>
</ObjectKey>
</Relationship>
</ObjectKey>
</Relationship>
</SearchCriteria>
<SearchInfo>
<SearchCriteria/>
<SearchCriteria/>
</SearchInfo>
<Payload/>
<AdditionalInfo/>
</cfmXML>
It contains the search criteria to be executed in the RMW System and result set to be returned to the caller. The search criteria contain attribute names and values to be used as search parameters, category to be searched upon, and the view to be used for search and results.
| cfmXML tag | Outbound Message | Inbound Message |
|---|---|---|
| <SearchCriteria execute> | Not Used | This contains the search criteria to perform the search. The execute attribute contains the information on whether to execute the search criteria and show the result. If value is "yes", the search is executed. |
| <CategoryName> | Not Used | Contains the name of the category for performing search. |
| <CategoryDBName> | Not Used | Contains the database name of the category for performing search. |
| <ViewName> | Not Used | Contains the name of the view for performing search. |
| <Attribute> | Not Used | Attribute (explained below) represents one attribute to search upon with search value. Search criteria may have multiple attributes each containing a search value. |
| <Relationship type refid name resolve> | Not Used | It contains reference to another object and associated search values to be searched upon in the database.
Type indicates if the relationship is inbound or outbound. Name specifies the name for the relationship as defined in the system. RefID and resolve are used for internal use cases by the RMW System. |
Specifies an object attribute. Usually, it represents value of a cell in the database.
| cfmXML tag | Outbound Message | Inbound Message |
| <Attribute name> | Contains the information about the attribute. Name attribute contains the name of the attribute. | Contains the information about the attribute. Name attribute contains the name of the attribute. |
| <Value dataType asEnteredValue> | Contains the value of the attribute. Attribute dataType contains the data type of attribute.
For example. String, Number and so on. Value can have following syntax <<Value>>- For single value <<Value>> to <<Value>> à upper and lower bounds to <<Value>> à upper bound <<Value >> to à lower bound |
Contains the value of the attribute (as stored in the system). Attribute dataType contains the data type of attribute.
For example. String, Number and so on. asEnteredValue contains the value for the attribute as was entered by the user, if applicable. Value can have following syntax <<Value>> - For single value <<Value>> to <<Value>> - upper and lower bounds to <<Value>> - upper bound <<Value >> to lower bound |
| <UnitOfMeasure> | Contains the value for unit of measure for the attribute value. | Contains the value for unit of measure for the attribute value. |
| <Format> | Contains format of Date
It can have following values dd/mm/yyyy, dd/mm/yyyy hh:mm:ss |
Contains format of Date
It can have following values dd/mm/yyyy, dd/mm/yyyy hh:mm:ss |
Contains information about other objects related to the object being defined in the message.
| cfmXML tag | Outbound Message | Inbound Message |
| <CategoryName> | Contains the category name of the related category. | Contains the category name of the related category. |
| <CategoryDBName> | Contains the database name of the category name of the related category. | Contains the database name of the category name of the related category. |
| <ObjectKey> | If the relationship is a PK, it contains the primary keys data from the related category. If the relationship is not a PK, ObjectKey is not needed. | If the relationship is a PK, it contains the primary keys data from the related category. If the relationship is not a PK, ObjectKey is not needed. Details of Object Key are explained in the next section. |
Contains unique ID for the object.
| cfmXML tag | Outbound Message | Inbound Message |
| <ObjectID> | Contains the unique ID in the system for this object. This is internal ID in the RMW System. | Contains the unique ID in the system for this object. This is internal ID in the RMW System. |
| <Attribute> | This can be zero or many. All these attributes indicate the primary keys of the object. | This can be one or many. All these attributes indicate the primary keys of the object. |
| <Relationship> | These are references to other objects which are part of the primary keys of the object. This can be zero or many. Relationships can be nested. | These are references to other objects which are part of the primary keys of the object. This can be zero or many. Relationships can be nested. |
<?xml version="1.0" encoding="UTF-8"?>
<cfmXML>
<LoginInfo/>
<SessionInfo/>
<PageInfo/>
<ScreenContext/>
<Response/>
<SearchCriteria/>
<SearchInfo/>
<Payload>
<Object name="name">
<CategoryDBName>String</CategoryDBName>
<ViewName>String</ViewName>
<ObjectKey/>
<ObjectDetail>
<Attribute/>
<Relationship/>
</ObjectDetail>
<Document type="attachment" fileName="String" mimeType="String">String</Document>
<OldValues>
<ObjectKey/>
<ObjectDetail/>
</OldValues>
<AdditionalInfo>
<Attribute/>
<Attribute/>
</AdditionalInfo>
</Object>
<ObjectGroup name="name">
<Object/>
<Object/>
</ObjectGroup>
</Payload>
<AdditionalInfo>
<AdditionalInfo>
</cfmXML>
Payloads contain data records. An object in a payload represents a single data record. Each object contains a key section for primary keys of the objects and detail section to store non-primary keys of the object. Objects also contain relationship information about the related objects.
| cfmXML tag | Outbound Message | Inbound Message |
|---|---|---|
| <Object> | Represents one object in the payload. There could be one or more objects in a payload. | Represents one object in the payload. There could be one or more objects in a payload. |
| <ObjectGroup> | Object Group contains one or more objects. This is similar to payload with the difference that object groups cannot be nested.
Each ObjectGroup represents objects which are part of single transactions. This is currently used for export and import feature of the RMW System. |
Object Group contains one or more objects. This is similar to payload with the difference that object groups cannot be nested.
Each ObjectGroup represents objects which are part of single transactions. This is currently used for export and import feature of the RMW System. |
Contains information related to single data object. Attribute operation contains information on what type operation to be performed on this object.
Operation attributes may have the following values:
I - for Insert operation.
U - for Update operation.
D - for Delete operation.
| cfmXML tag | Outbound Message | Inbound Message |
| <CategoryName> | Contains the category name of this object. | Contains the category name of this object. |
| <CategoryDBName> | Contains the category database name of this object. | Contains the category database name of this object. |
| <ViewName> | Contains the view name of this object. | Contains the view name of this object. |
| <ObjectKey> | This contains the information on object's primary keys | This contains the information on object's primary keys |
| <ObjectDetail> | This contains the information on object's non primary keys. It can contain zero or more attributes and relationships. | This contains the information on object's non primary keys. It can contain zero or more attributes and relationships. |
| <Document> | Contains text or binary document information related to this object. There could be zero or more of such documents. XML parser ignores the content of this tag. | Contains text or binary document information related to this object. There could be zero or more of such documents. XML parser ignores the content of this tag. |
| <OldValue> | This is used when there is a change in the values of the object. It stores all the values before the change is/was applied to the object. It consists of object keys and details. It is currently used internally by the RMW System. | This is used when there is a change in the values of the object. It stores all the values before the change is/was applied to the object. It consists of object keys and details. It is currently used internally by the RMW System. |
This contains information, which cannot be represented as part of any object. These are message and object level tags. Any number of Attribute tags can be specified under AdditionalInfo. These may constitute the information that is needed for the message receiving application, for any special processing.
This section can be used extensively for various general use cases.
