| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
 Previous |
 Next |
| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
Previous |
Next |
This chapter describes the Agile e6 Core Web Services operations. The use of these operations to process the bulk requests is described in section Bulk Processing of Requests.
Some of the operations, such as getRelations, require counting the number of records. For more information on these, see section countOnly Query Support in this document.
For additional information on these Web Services and operations, the following documents will also be available from the Oracle Software Delivery Cloud website: https://edelivery.oracle.com:
Agile e6 Web Services Schema Docs, including the PLM Data Types document
Agile e6 Web Services SOAP Samples
Certain situations require several calls to be made to a Web Service operation. In a WAN environment, calling the operation several times would result in an unacceptable performance penalty. So it is critical to limit the number of Web Service calls for each use case. Therefore, most of the Agile e6 Web Service operations support bulk mechanism.
Example:
Instead of calling the Web Service operation BusinessObjectService.createObject one hundred times, you can call the operation BusinessObjectService.AN and assign a list of the one hundred single requests to create an object. Each nested request in the bulk call has the full flexibility of the single request, so it is possible to create ten projects, fifty items and forty documents in one bulk call.
To link the objects together, you can call another bulk operation called BusinessObjectService.createRelationBulk.
|
Note: You are allowed to create a complex graph of objects in only two Web Service calls. |
|
Note: The bulk mechanism can be configured to either stop on the first failure of a nested request, or to continue and report all errors and warnings that occurred during the processing of the nested requests. |
The result is a bulk response with nested responses, matching the list of nested requests in the bulk request.
Most of the Agile e6 Web Service operations support bulk processing of requests. The operations with one request input object and one response output object can be configured to process multiple or bulk requests and corresponding responses.
A bulk request contains a list of requests for the non-bulk operation. These requests are executed one by one, and each response is stored in the result list of the bulk response object. All requests contained in the bulk request list are executed in sequence using the order of the list, as a result of which the results are in random sequence. The bulk requests can be configured to either stop on the first failure, or to continue regardless of a failing request.
If a request fails with a response FAILURE, the loop is aborted if the stopOnFailure member of the bulk request is set. If stopOnFailure is not requested, the status of the bulk response is set to PARTIAL_SUCCESS. This requires you to look into each response in the list to check the individual status.
However, if a request fails with a PlmFault (or any other exception), the bulk processing is aborted and the list of requests processed until the fault occurred is returned. Additionally, the causing fault is returned in the bulk response.
If the bulk request does not contain any request, a WARNING response is returned.
The content of the response object depends on the status code, as listed below:
| SUCCESS | A list with all response objects matching the list of requests.
All requests succeeded. |
| FAILURE | A list with all response objects matching the list of requests.
One or more requests failed, check the respective responses. The last executed request failed with an exception, which is returned as the fault in the bulk response. If one request fails due to lack of mask in Whitelist, status code would be FAILURE instead of PARTIAL_SUCCESS even if other services are successful. |
| WARNING | The bulk request does not contain any request. |
| PARTIAL_SUCCESS | A list with all response objects matching the list of requests.
One or more requests failed, check the respective responses. If stopOnFailure was requested, the list ends with the first response that failed. |
The BusinessObject Web Service enables you to create retrieve, update, and delete PLM objects belonging to an entity, an entity type, and a relation. All operations require one request object as input, and return one response object.
The request contains attribute values used to search or create a PLM object.
The response contains the data of the respective objects.
Bulk operations allow you to execute a whole list of requests with a single Web Service call. The response of a bulk operation contains a list of responses matching the list of requests.
The PLM objects are read from the Agile e6 application using the mask specified in the request. It is only possible to access Agile e6 attributes that are visible in this mask, with the exception of the ID fields EDB_ID and C_ID. Only the masks listed in the Web Service Whitelist of the Agile e6 application can be accessed.
Use the EBD_ID if you need to keep the reference to a PLM object, especially if it is stored in another system.
The C_ID needs to be used only to build internal object graphs, for instance when filling a UI element.
|
Note: Not all PLM objects have an EDB_ID or a C_ID. Check the customization of the respective Agile e6 system before deciding how to make external references to PLM objects of that system. |
All operations allow you to specify the attributes that you require to return from the PLM object. If no return attributes are specified, all the accessible attributes are returned, which correspond to all visible fields of the mask. Optionally, all languages of multi-lingual attributes can be returned, but may result in a considerably larger response object.
It is possible to request the transfer of binary data (BLOBs). However, by default, binary data is not transmitted; binary attributes that are to be transferred need to be visible in the underlying Agile e6 mask. BLOBs are transferred using the MTOM feature of JAX-WS.
The following are the bulk operation names of the single request operations for Business Object Web Services describing the concurrent sections.
createObjectBulk
getObjectsBulk
updateObjectBulk
deleteObjectBulk
createRelationBulk
updateRelationBulk
getRelationsBulk
deleteRelationBulk
setReservationBulk
Service
To create an object in the Agile e6 system.
Usage
The request includes a PlmObject which describe the object to create and a PlmResult to define the return values of the response. By default, the response returns values of all visible fields (plus some important ID fields like EDB_ID and C_ID) that are contained in the mask.
Response information can be restricted by defining the list of fields that must be returned in the PlmResult of the request, but note that you can only return values for fields which are available in the mask. The settings of the mask determines the sorting of the data. Return values are provided in a standardized format as marshaled by the JAXB framework. Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value is retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
If the object already exists in Agile e6, or an error occurs during creation of the object, an error code is returned.
Request Type
CreateObjectRequestType
messageId (String): ID to be returned in the response (optional)
messageName (String): Name to be returned in the response (optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmObject: The PLM class reference and a list of object attributes (name/value pairs) used to create the new object.
The metadata of the plmObject is currently ignored by this operation, thus you can pass empty values for these elements.
Only the list of attribute values is used to fill the new record in Agile e6.
plmResult: Describes how the result of the operation is returned to the client.
| attributeNames (Boolean) | List of field names to be returned |
|
| includeBinaryValues (Boolean) | Include binary values? |
|
| includeAllLanguages (Boolean) | Include all languages? |
|
Response Type
CreateObjectResponseType
statusCode (ResponseStatusCode):
| SUCCESS | The newly created PLM object including all attributes defined by the PlmResult of the request. |
| PARTIAL_SUCCESS | The newly created PLM object including some of the attributes defined by the PlmResult of the request. |
| FAILURE | A faulty description including an error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
object (PlmObject): The object created by this operation.
It contains the attributes requested in the PlmResult, or all visible attributes if no attributes have been requested.
Service
To retrieve the requested objects from the Agile e6 system.
Usage
It executes a query in the Agile e6 system and returns the matching objects. The operation uses the mask that is specified in the request to retrieve the data (search in mask).
Response information can be restricted by defining the list of fields that must be returned. Note that you can get the values only for fields that are available in the mask.
The sorting of data determines the settings of the mask.
Date values are returned in UTC, based on the assumption that the data returned by the EDM server is in Server Local Time.
By default, only the current language value is retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
Objects for which the current user does not have access to, does not show up in the response (this is contrary to client behavior where one can see such objects as dotted (...) objects. At the server, this is controlled by a DataView default.
The countOnly flag of the request is very important here. For more information on this, refer to countOnly Query Support in this document.
Request Type
GetObjectsRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmQuery (PlmQuery):
plmClass: The object type as a PlmClassRef (PLM class reference, as provided by the metadata service).
selection: A list of PlmCondition objects representing the search criteria for object attributes.
| ignoreRecordLimit (Boolean) | Ignore the record limit? |
|
| countOnly (Boolean | Count only? |
|
| attributeNames (Boolean) | List of field names to be returned? |
|
| includeBinaryValues (Boolean) | Include binary values? |
|
| includeAllLanguages (Boolean) | Include all languages? |
|
Response Type
GetObjectsResponseType
statusCode (ResponseStatusCode):
| SUCCESS | The query was executed without any problem. The list of objects might be empty. |
| PARTIAL_SUCCESS | One or more attributes, defined by the PlmResult of the request, were not found in the queried objects. Details can be found in the list of warnings and exceptions. |
| FAILURE | A faulty description including error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
recordLimitHit (Boolean): Indicates whether the query result has hit the mask limit.
objects: List of objects (PlmObject) found including all the object attribute values listed in the PlmResult of the request.
If a count request was made, the response will have one PlmObject with an Integer attribute named COUNT containing the number of objects matching the query, and an Integer attribute called RECORD_LIMIT containing the current record limit of the mask used for the count operation.
Service
To update an object in the Agile e6 system.
Usage
The operation supports an automatic creation of an object if it was not found. The flag autoCreate in the request controls this behavior.
By default, the response returns values of all visible fields (plus some important ID fields like EDB_ID and C_ID) that are contained in the mask. The response information can be restricted by defining the list of fields that must be returned in the PLM Result of the request, but note, that you can only return values for fields which are available in the mask. The settings of the mask determines the sorting of the data. Return values are provided in a standardized format as marshaled by the JAXB framework. Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value is retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
If an error occurs while creating the object, an error message is returned.
Request Type
UpdateObjectRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmObject: The PLM class reference, the ID of the object to update, and a list of object attributes (name/value pairs) used to update or create the object.
| autoCreate (Boolean) | Automatically create the object if it does not exist. |
|
plmResult: Describes how the result of the operation is returned to the client.
| attributeNames (Boolean) | List of field names to be returned |
|
| includeBinaryValues (Boolean) | includeBinaryValues (Boolean) |
|
| includeAllLanguages (Boolean) | Include all languages |
|
Response Type
UpdateObjectResponseType
statusCode (ResponseStatusCode):
| SUCCESS | The newly created PLM object, including all attributes defined by the PlmResult of the request. |
| PARTIAL_SUCCESS | The newly created PLM object including some of the attributes defined by the PlmResult of the request. |
| PARTIAL_SUCCESS | A fault description including error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PLMWarningType) that occurred during the operation.
exceptions: List of exceptions (PLMExceptionType) that occurred during the operation.
object (PLMObject): The object updated or created by this operation.
It contains the attributes requested in the PlmResult, or all visible attributes if no attributes have been requested.
autoCreated (Boolean): This flag is true, if the object has been created by this operation, and false if the object has been updated.
Service
To delete an object in the Agile e6 system.
Usage
|
Note: The object is deleted permanently without using the trash basket. |
A mask can be specified, which is used to process the delete operation. This allows to fire customer specific triggers on the EDM server during record deletion.
Request Type
DeleteObjectRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmObject (PlmObject or PlmObjectRef): The PLM class reference and the ID query of the object to be deleted.
Response Type
DeleteObjectResponseType
statusCode (SUCCESS or FAILURE)
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PLMWarningType) that occurred during the operation.
exceptions: List of errors (PLMExceptioType) that occurred during the operation.
object (PLMObject): PLM object with ID information like EDB_ID and C_ID, if available (optional).
This is only returned if the object is found, but the operation fails.
Service
To create a relation between one parent object and one child object of an Agile e6 entity.
Usage
The request includes a PlmObject which describes the relation object to create a PlmObjectReference for the parent and the child object, a PlmMetaRelation object defining the relation between them and a PlmResult to define the return values of the response.
By default, the response returns values of all visible fields (plus some important ID fields like EDB_ID and C_ID) that are contained in the mask.
Response information can be restricted by defining the list of fields that must be returned in the PlmResult of the request, but note that you can only return values for fields which are available in the mask. The settings of the mask determines the sorting of the data. Return values are provided in a standardized format as marshaled by the JAXB framework.
Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value is retrieved for multi-lingual fields. However, the web service client can request to retrieve all language values in the same call.
If the object already exists in Agile e6, or an error occurs while creating the relation object, an error code is returned.
Request Type
CreateRelationRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
relationObject (PlmObject): The relation Object with the PLM class reference and a list of relationship attributes (name/value pairs) used to create the new object.
The metadata of the relationObject is currently ignored by this operation, so you can pass empty values for these elements.
Only the list of attribute values is used to fill the new relation record in Agile e6.
parent (PlmObjectRef) Object reference: This is either a PlmObject as returned by the BusinessService.getObjects operation, or a PlmObjectReference containing the query for the record.
child (PlmObjectRef) as object reference: This is either a PlmObject as returned by the BusinessService.getObjects operation, or a PlmObjectReference containing the query for the record.
relation (PlmMetaRelation) a relationship metadata: This is a PlmMetaRelation as returned by the MetadataService.getRelation operation. It defines the relation of the parent and the child object.
plmResult (PlmResult): This describes how the result of the operation is returned to the client.
| attributeNames (Boolean) | List of field names to be returned? |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages? |
|
Response Type
CreateRelationResponseType
statusCode (ResponseStatusCode)
| SUCCESS | The newly created PLM object including all attributes defined by the PlmResult of the request. |
| PARTIAL_SUCCESS | The newly created PLM object including some of the attributes defined by the PlmResult of the request. |
| FAILURE | A faulty description including error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
relationObject (PlmObject): The created PLM relation object contains the attributes listed in the PlmResult of the request.
Additionally, the ID attributes of the parent and the child record are added.
The parent IDs are named PARENT.EDB_ID and PARENT.C_ID, the attributes for child IDs are named CHILD.EDB_ID and CHILD.C_ID.
This is necessary to prevent name clashes if the parent and child entity are the same (for instance in an Item BOM).
Service
Updates an existing relationship entry in the Agile e6 system.
Usage
By default, the response returns values of all visible fields (plus some important ID fields like EDB_ID and C_ID) that are contained in the mask. The response information can be restricted by defining the list of fields that must be returned in the PlmResult of the request, but note, that you can only return values for fields which are available in the mask. The settings of the mask determines the sorting of the data. Return values are provided in a standardized format as marshaled by the JAXB framework. Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value is retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
If the object already exists in Agile e6, or an error occurs while creating the relation object, an error code is returned.
Request Type
UpdateRelationRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmRelationQuery (PlmRelationQuery):
PlmObject or PlmObjectReference: Defines the parent record of the relation. This is either a PlmObject as returned by the BusinessObject Web Service, or (to improve the performance) only a reference to it.
PlmMetaRelationRef: The metadata of the relation to be read (parent, child, type, view). This allows specifying the aggregate, refined, constraint, or type relation.
Selection: A list of PlmCondition objects representing the search criteria for object attributes. The rest of the PlmRelationQuery members are ignored.
relationObject (PlmObject): The relation object with the PLM class reference, and a list of relationship attributes (name/value pairs) is used to create the new object.
plmResult (PlmResult): This describes how the result of the operation is returned to the client.
| attributeNames (Boolean) | List of field names to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
Response Type
UpdateRelationResponseType
statusCode (ResponseStatusCode)
| SUCCESS | The newly created PLM object including all attributes defined by the PlmResult of the request. |
| PARTIAL_SUCCESS | The updated PLM object including only some of the attributes defined by the PlmResult of the request. |
| FAILURE | A faulty description including error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
relationObject (PlmObject): The updated PLM relation object contains the attributes listed in the PlmResult of the request.
Additionally, the ID attributes of the parent and the child record are added.
The parent IDs are named PARENT.EDB_ID and PARENT.C_ID, the attributes for child IDs are named CHILD.EDB_ID and CHILD.C_ID.
This is necessary to prevent name clashes if the parent and child entity are the same (for instance in an Item BOM).
Service
To get the relationship records of a PLM object for a specified PLM relation.
Usage
The operation executes a query in the Agile e6 system and returns the list of matching relationship records of a PLM object for a specified PLM relation.
The operation allows reading aggregate, refined, constraint, and type relation.
The countOnly flag of the request is very important here. For more information on this, refer to countOnly Query Support in this document.
Request Type
CreateRelationRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmRelationQuery (PlmRelationQuery):
PlmObject or PlmObjectReference: To get the parent record of the relation. This is either a PlmObject as returned by the BusinessObject Web Service or - to improve performance - only a reference to it.
PlmMetaRelationRef: The metadata of the relation to be read (parent, child, type, view).
This allows you specifying the aggregate, refined, constraint, or type relation.
selection: A list of PlmCondition objects representing the search criteria for object attributes.
| ignoreRecordLimit (Boolean) | Ignore the record limit |
|
| countOnly (Boolean) | Count only |
|
| attributeNames (Boolean) | List of field names to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
Response Type
GetRelationsResponseType
Status code (SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE).
A PLM ticket (String)
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed or - in case of a backward flow - if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warning: List of warnings (PlmWarningType) that occurred during the operation.
List of errors (PlmExceptionType) that occurred during the operation.
Record limit hit? [true/false]: Indicates if the query result has hit the mask limit.
List of objects (PlmObject) found including all the object attribute values listed in the PlmResult of the request.
Additionally, the ID attributes of the parent and the child record are added. The parent IDs are named PARENT.EDB_ID and PARENT.C_ID, the attributes for child IDs are named CHILD.EDB_ID and CHILD.C_ID.
This is necessary to prevent name clashes if the parent and child entity are the same (for instance in an Item BOM).
If a count request was made, the response will have one PlmObject with an Integer attribute named COUNT containing the number of objects matching the query, and an Integer attribute called RECORD_LIMIT containing the current record limit of the mask used for the count operation.
Service
Deletes a relationship entry in the Agile e6 system.
Usage
|
Note: The object is deleted permanently without using the trash basket. |
A mask can be specified, which is used to process the delete operation. This allows to fire customer specific triggers on the EDM server during record deletion.
Request Type
DeleteRelationRequestType
plmRelationQuery (PlmRelationQuery):
PlmObject or PlmObjectReference: Defines the parent record of the relation. This is either a PlmObject as returned by the BusinessObject Web Service, or - to improve performance - only a reference to it.
PlmMetaRelationRef: The metadata of the relation to be read (parent, child, type, view). This allows specifying the aggregate, refined, constraint, or type relation.
Selection (List<PlmCondition>: A list of PlmCondition objects representing the search criteria for object attributes. This query has to match exactly one relation record, otherwise the operation fails. The rest of the PlmRelationQuery members are ignored.
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
DeleteRelationResponseType
status code (ResponseStatusCode):
| SUCCESS | Relation object is deleted. |
| FAILURE | A faulty description including error message and the type of error. |
A PLM ticket (String)
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
plmObject (PlmOjbect): PLM object with ID information like EDB_ID and C_ID, if available (optional). This is only returned if the object is found, but the operation fails.
Service
The Web Service operates similar to the corresponding ECI functions:
eci_res_ent
eci_fre_ent
Usage
Reserves or un-reserves an object (usually a document object) in the Agile e6 system.
Request Type
SetReservationRequestType
plmObject (PlmObject or PlmObjectRef): The PLM entity reference and the ID query of the object to be reserved.
Boolean value true or false:
True = reserved
False = un-reserved
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
SetReservationResponseType
status code (ResponseStatusCode):
| SUCCESS | Object is reserved/un-reserved. |
| FAILURE | A faulty description including error message and the type of error. |
A PLM ticket (String)
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
plmObject (PlmOjbect): PLM object with ID information like EDB_ID and C_ID, if available (optional). This is only returned if the object is found, but the operation fails.
A document is a business object that specifies one or more files that are stored in the Agile e6 File Vault. You can load a document and add one or more files to its files table. You can also search for a document and its files, like searching for an item. The CAD fastload feature is available via the getCADAssembly Web Service.
|
Note: Before continuing with DFM Support, please refer for further information about the DFM Web Service Configuration, to the Administration Guide for Agile e6.2.0.0. |
The upLoadFile and downLoadFile web services, which are not a part of the core Services and are deployed as File Services, are used to access the local File Server on the remote DFM location. The file services are deployed on WebLogic and for remote DFM locations on TOMCAT.
The use cases describe how different Web Services interact to implement a DFM operation.
In a DFM environment are two or more file servers involved. For each DFM site (remote location) is a file server installed. File operations like check-in or check-out are executed by calling the local web services.
In the following overview, the remote location has a file server and the StreamingFileService deployed. The Web Service client, for example a CAD integration runs on the remote location and calls the CoreServices which are deployed on the main location to communicate with the EDM server. All file operations are executed on the remote location by calling the local deployed StreamingFileService. The StreamingFileService communicates with the local File Server to exchange files and with the CoreServices to maintain the metadata within Agile e6.
In case a requested file is not available or out-dated on the local File Server, the local File Server requests the file from the File Server on which the file is available.
To download a file from the local File Server, the Web Service client has to contact the CoreServices to connect to the Agile e6 system.
The Web Service client has to call the setUserContext Web Service to set the DFM site which should be used.
Flow:
The Web Service Client wants to check-out a file. To start this, the client calls the getFiles or getCADAssembly Web Service.
The getFiles Web Service gains the information from the Agile e6 system (DFM support).
The file and vault lists of the document are returned.
The getFiles Web Service sends a response which can be used to call the downloadFile Web Service.
The Web Service client calls the downloadFile Web Service to download the file.
The downloadFile Web Service replicates the file from the remote File Server if necessary.
The File Server request the file from the remote File Server.
The file will be replicated.
The file name of the replicated file is returned and ready for download.
Return the file stream to the client.
The downloadFile Web Service calls the updateFileObject Web Service to update the metadata within Agile e6.
The updateFileObject Web Service to update the metadata within Agile e6.
The metadata is updated.
Successful call.
If necessary, delete the old file version.
Successful call.
In the installed environment, these are deployed as the StreamingFileService web application, containing the DocumentFileService Web Service. It is deployed on WebLogic and for remote DFM locations on TOMCAT.
downloadFile
uploadFile
Service
Downloads a file directly from the local File Server. The request needs the response data provided by the getFiles or getCADAssembly Web Service call.
Usage
The Web Service is deployed on a separate installation on the local DFM location. The service can be deployed on a TOMCAT or WebLogic server.
If the Web Service is deployed on WebLogic, we recommend updating metadata (file replication) directly. Do not use the updatedFileObject Web Service for this.
The deployment only needs tracing.
The Web Service should use the HTTPs protocol to secure the file transfer.
Request Type
downloadFileRequestType
messageId (String, required)
messageName (String, required)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
statusCode (ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE.
url (String, optional)
The URL to the createUpdateFileObject Web Service.
fmsVaultTokens (List<PlmFMSVaultToken>, required)
PlmFMSVaultToken
Containing all attributes to contact the File Server via FMS Java Daemon.
| vaultName | String, required |
| vaultType | String, required |
| vaultKind | String, required |
| vaultNode | String, required |
| vaultNetRef | String, required |
| vaultPath | String, required |
| fmsJadeNode | String, required |
| fmsJadePort | String, required |
| tokenTimestamp | String, required |
| token | String, required |
fmsToken (PlmFmsToken, required)
PlmFmsToken
Containing all attributes to contact the File Server via FMS Java Daemon.
| id | String, required | Document to file relation record CID |
| parentId | String, required | Document to file relation record parent CID (Document CID) |
| childId | String, required | Document to file relation record child CID (File CID) |
| sourceFileToken | PlmFMSFileToken, optional | |
| targetFileToken | PlmFMSFileToken, required |
Response Type
downloadFileResponseType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
fileData (a javax.activation.DataHandler, optional)
The file data as a binary MTOM stream with content type "application/octet-stream".
Use the streaming API of your JAX-WS implementation to transfer the file.
|
Note: If streaming is not used, the file is transferred to XML data. This can lead to performance issues, creates big SOAP messages, and can cause an OutOfMemoryException on the server or client. |
Service
Uploads a file directly to the local File Server. The request needs the response data provided by the getFMSVault Web Service call.
Usage
The Web Service is deployed on a separate installation on the local DFM location. The service can be deployed on a TOMCAT or WebLogic server.
If the Web Service is deployed on WebLogic, we recommend updating metadata (file replication) directly. Do not use the createUpdatedFileObject Web Service for this.
The deployment only needs tracing.
The Web Service should use the HTTP/S protocol to secure the file transfer.
The request contains a token which allows the Web Service client to upload a file into a specific vault.
The URL, document and file reference, allows the Web Service to contact the createUpdateFileObject Web Service to update the metadata in Agile e6.
For authentication, the PLM ticket can be used, or a system account.
Request Type
uploadFileRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
ticket (String, required) The PLM ticket is used to call createUpdateFileObject () Web Service.
DocumentFileQuery (PlmDocumentFileQuery, required)
| Document | PlmObjectRef, required | The Agile e6 document object as PlmObjectRef |
| documentFileMaskName | String, required | The document file relation list to use for the query |
| Selection | List<PlmCondition>, required | List of PlmConditions which contain the field name/value pairs to search for document records |
| ignoreRecordLimit | Boolean, optional | A flag indicating if the record limit should be ignored (default = false) |
| attributeNames | List<String>, optional | Inherited from PlmResult |
| includeBinaryValues | Boolean, optional | Inherited from PlmResult |
| includeAllLanguages | Boolean, optional | Inherited from PlmResult |
documentFileObject (PlmObject, required)
The relation object with the Agile e6 class reference, and a list of relationship attributes (name/value pairs) used to create the new object.
The metadata of the relationObject is currently ignored by this operation, thus empty values for these elements can be passed.
Only the list of attribute values is used to fill the new relation record in Agile e6.
url (String, required) The URL to the createUpdateFileObject Web Service.
fmsVaultToken (PlmFMSVaultToken, required)
PlmFMSVaultToken Contains all attributes to contact the File Server via FMS Java Daemon.
| vaultName | String, required |
| vaultType | String, required |
| vaultKind | String, required |
| vaultNode | String, required |
| vaultNetRef | String, required |
| vaultPath | String, required |
| fmsJadeNode | String, required |
| fmsJadePort | String, required |
| tokenTimestamp | String, required |
| token | String, required |
fileDate (javax.activation.DataHandler, required)
Response Type
uploadFileResponseType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
dfmResult (DFMResultData, optional)
|
Note: A PlmFault will be thrown if an unexpected technical problem occurs, e.g. connection loss. |
All operations in DocumentManagement Web Service support DFM.
|
Note: To create a document, use the Business Object Web Services. |
The following are the Web Service operation names of the single request operations for DocumentManagement Web Services describing the concurrent sections:
getFiles
getCADAssembly
getCADAssemblyNextDataBlock
getFMSVault
createUpdateFileObject
Service
Retrieves the list of files assigned to a specific document.
The operation will use the document file relation mask that is specified in the request to retrieve the data - search in a mask.
Usage
The response provides the necessary data to call the downloadFile Web Service and is divided into the following parts:
List of Vault definitions including:
FMS Server definition
FMS Java Daemon definition
FMS vault tokens
List of FMS file token including:
Source file with file tokens
Target file with file tokens
|
Note: In case of replication, the source file and target file will be filled. Otherwise, only the target file will be filled. |
List of files
By default, the response will return values of all visible document file relation fields, plus some important ID fields (e.g. EDB_ID and C_ID) that are contained in the mask. Response information can be restricted by defining the list of fields that should be returned.
|
Note: Only values for fields, which are available in the mask, can be returned. The settings of the mask will determine the sorting of the data. |
The response will return file information and vault information. Return values will be provided in a standardized format as marshaled by the JAXB framework. Date values will be in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value will be retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
The method fills a list of vault in the form of PlmFMSVaultToken in the response, which are referenced in one or many from the PlmFMSTokens.
The file tokens in the form PlmFMSTokens in response contains file details and its generated access tokens. Each file token represents one file from the file list and can be referenced by doc_fil ID.
The bulk operation is called getFilesBulk.
Request Type
GetFilesRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmDocumentFileQuery (PlmDocumentFileQuery):
| document (PlmObjectRef, required) | The Agile e6 document object as PlmObjectRef reference. |
| documentFileMaskName (String required) | The document file relation list to use for the query. |
| Selection (list<PlmCondition>, required) | List of PlmConditions which contain the field name/value pairs to search for document records. |
| ignoreRecordLimit (Boolean, optional) | A flag indication if the record limit should be ignored (default is false). |
| excludeVaultValues (Boolean, optional) | A flag indication if the vault values should be returned, too (default is true). |
| attributeNames (List<String>, optional) | Inherited from PlmResult. |
| includeBinaryValues (Boolean, optional) | Inherited from PlmResult. |
| includeAllLanguages (Boolean, optional) | Inherited from PlmResult |
Response Type
GetFileResponeType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
recordLimitHit (Boolean, required)
[true|false] Indicates whether the query result has hit the mask limit.
url (String, optional)
The URL to the createUpdateFileObject Web Service.
fmsVaultTokens (List<PlmFMSVaultToken>, optional)
List of PlmFMSVaultToken containing all attributes to contact the File Server via FMS Java Daemon.
| PlmFMSVaultToken |
|
fmsTokens (List,PlmFMSToken>, optional)
List of PlmFMSToken containing all attributes to contact the File Server via FMS Java Daemon.
| PlmFMSToken |
|
objects (List<DFMResultData>, required)
List of Document File relation records found.
| DFMResultData |
|
The created objects contain the attributes listed in the request.
In case one or more of the requested attributes do not exist, PARTIAL_SUCCESS is returned.
In case one or more of the requested attributes are not accessible, a WARNING is returned.
If no attributes have been requested (attribute list is missing), the whole object including all visible attributes and the ID attributes (EDB_ID and C_ID) are returned. If none of the requested attributes exists, or the list is empty, only the ID attributes (EDB_ID and C_ID) are returned.
Service
Retrieves the list of document structure records and files needed to load a 3D assembly into a CAD system.
The operation is similar to the fastload ECI function which allows collecting all files required to represent a CAD assembly. The CAD fastload feature is also available for this Web Service.
Usage
The Web Service uses the stored procedure to traverse the CAD structure and to create the document hierarchy list and the file list. This stored procedure specifics of the CAD structures like external references, drawings, family tables, etc. takes into account.
|
Note: See also ECI function eci_loa_cax for more details on the required parameters. |
The Web Service is used to load the document structure according to:
the version view which is currently active
the snapshot view (baseline).
The Web Service returns the hierarchical document structure information and the list of files.
|
Note: In case of the snapshot, the Web Service returns a flat list of document instead of the document hierarchy. |
The entry point is a document.
Snapshot (Baselines) handling requires providing additional information when calling this Web Service. The Snapshot-ID identifies the snapshot to be loaded.
The response provides the necessary data to call the downloadFile Web Service and is divided into the following parts:
List of vault definitions including:
FMS Server definition
FMS Java Daemon definition
List of files
List of document hierarchy
By default, the response returns values provided by the temporary table used by the stored procedure.
The response information can be restricted by defining the list of fields that must be returned, but note that you can only return values for fields which are available in the temporary table.
The stored procedure checks if all files are available of the DFM location. If one or more files are out-dated the procedure marks the records with the DFM status.
The response returns file information and vault information (see Response Type). Return values are provided in a standardized format as marshaled by the JAXB framework. Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
|
Note: Since the operation handles large structures, there will be no bulk support. |
Request Type
GetCADAssemblyRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmDocumentCADQuery (PlmDocumentCADQuery):
| document (PlmObjectRef, required) | An object reference to the document. |
| creationSystem | (String, required) |
| logicType | (String, required) |
| structureFlag | (boolean, required) |
| bomFunction | (String, required) |
| snapshotID (String, optional) | The ID of the snapshot. |
| externalReferences (boolean, optional) | Obey external references for snapshots?
|
plmFileResult (PlmResult, optional): This describes how the result of the operation is returned to the client.
| attributeNames(List<String>) | List of field names of the file list to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
| omitEmptyValues (Boolean) | Omit empty attribute values from the response |
|
plmDocStrResult (PlmResult, optional): This describes how the result of the operation is returned to the client.
| attributeNames(List<String>) | List of field names of the document structure list to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
| omitEmptyValues (Boolean) | Omit empty attribute values from the response |
|
Response Type
GetCAD AssemblyResponeType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the PLM session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
fileWidgetID (String, optional)
structureWidgetID (String, optional)
url (String, optional)
The URL to the createUpdateFileObject Web Service. This URL is provided if DFM is active.
fmsVaultTokens (List<PlmFMSVaultToken>, optional)
List of PLMFMSVaultToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSVaultToken |
|
fmsTokens (List,PlmFMSToken>, optional)
List of PlmFMSToken containing all attributes to contact the file server via FMS Java daemon.
| PlmFMSToken |
|
files (List<DFMResultData>, optional)
List of Document to File relation records found.
| DFMResultData |
|
structure (List<DFMResultData>, optional)
List of Document to Document relation records found.
| DFMResultData |
|
The created objects contain the attributes listed in the request.
In case one or more of the requested attributes do not exist, PARTIAL_SUCCESS is returned.
In case one or more of the requested attributes are not accessible, a WARNING is returned.
If no attributes have been requested (attribute list is missing), the whole object including all visible attributes and the ID attributes (EDB_ID and C_ID) are returned. If none of the requested attributes exists, or the list is empty, only the ID attributes (EDB_ID and C_ID) are returned.
Service
The service retrieves the next set of data for the widget IDs and closes if the next set of data is empty. It does not open the new widgets.
Usage
This operation can only be used in conjunction with "getCADAssembly" webservice. This service takes the widgetIDs of file and structure for the mask EDB-CAX-FIL-TMP-SLI and EDB-CAX-STR-TMP-SLI, which is returned by the getCADAssembly service.
Request Type
GetCADAssemblyNextDataBlockRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
fileWidgetID (String, optional)
structureWidgetID (String, optional)
plmFileResult (PlmResult, optional)
This describes how the result of the operation is returned to the client.
| attributeNames(List<String>) | List of field names of the file list to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
| omitEmptyValues (Boolean) | Omit empty attribute values from the response |
|
plmDocStrResult (PlmResult, optional):
This describes how the result of the operation is returned to the client.
| attributeNames(List<String>) | List of field names of the document structure list to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
| omitEmptyValues (Boolean) | Omit empty attribute values from the response |
|
Response Type
GetCAD AssemblyResponeType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
fileWidgetID (String, optional)
structureWidgetID (String, optional)
url (String, optional)
The URL to the createUpdateFileObject Web Service. This URL is provided if DFM is active.
fmsVaultTokens (List<PlmFMSVaultToken>, optional)
List of PLMFMSVaultToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSVaultToken |
|
fmsTokens (List,PlmFMSToken>, optional)
List of PlmFMSToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSToken |
|
files (List<DFMResultData>, optional)
List of Document to File relation records found.
| DFMResultData |
|
structure (List<DFMResultData>, optional)
List of Document To Document relation records found.
| DFMResultData |
|
The created objects contain the attributes listed in the request.
In case one or more of the requested attributes do not exist, PARTIAL_SUCCESS is returned.
In case one or more of the requested attributes are not accessible, a WARNING is returned.
If no attributes have been requested (attribute list is missing), the whole object including all visible attributes and the ID attributes (EDB_ID and C_ID) are returned. If none of the requested attributes exists, or the list is empty, only the ID attributes (EDB_ID and C_ID) are returned.
Service
This operation gets the upload information for different types of documents, Cax, file and creation systems, or for the given vault name that is used if DFM is not active.
Usage
The Web Service client provides the different needed combinations as request and gets the information for the upload. The provided metadata will be cached for later use (createUpdateFileObject)
Request Type
getFMSVaultRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
document (PlmObjectRef, optional)
An object reference to the document (the parent).
fileFormat (String, optional)
stepCreationSystem (String, optional)
The Step Creation System.
vaultName (String, optional)
The vault name for which details will be retrieved.
Response Type
getFMSVaultResponseType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
fileData (javax.activation.DataHandler, optional)
The file data as a binary MTOM stream with content type "application/octet-stream".
Use the Streaming API of your JAX-WS implementation to transfer the file. If streaming is not used, the file is transferred to XML data, which takes considerably longer leading to huge SOAP messages, and might even result in an OutOfMemoryException on the server or the client.
|
Note: This Web Service is used only internally and is only called by the system. |
Service
This Web Service creates and updates the metadata for the upload file object.
Usage
The Web Service implements two different use cases - one called from uploadFile, and the other called from downloadFile to finish a relocation.
Request Type
CreateUpdateFileRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
documentFileQuery (PlmDocumentFileQuery, optional used by uploadFile):
| document (PlmObjectRef, required) | The PLM document object as PlmObjectReference. |
| documentFileMaskName (String, optional) | The document file relation list to use for the query. |
| selection (List<PlmCondition>, required) | List of PlmConditions which contain the field name/value pairs to search for file records. |
| ignoreRecordLimit (boolean, optional | A flag indicates if the record limit should be ignored. The default is false. |
| attributeNames (List<String>, optional) | inherited from PlmResult |
| includeBinaryValues (boolean, optional) | inherited from PlmResult |
| includeAllLanguages (boolean, optional) | inherited from PlmResult |
documentFileobject (PlmObject, optional user by uploadFile) the relation Object with the PLM class reference and a list of relationship attributes (name/value pairs) used to create the new object.
The metadata of the relationObject is currently ignored by this operation, thus empty values can be passed for these elements. Only the list of attribute values is used to fill the new relation record in Agile e6.
documentCid (String, optional)
Used by downloadFile (replication), document C_ID.
fileCid (String, optional)
Used by downloadFile (replication), fileC_ID.
docFileCid (String, optional)
Used by downloadFile (replication), fileC_ID.
fileCrypName (String, required)
fileSize (String, required)
vaultName (String, required)
Response Type
CreateUpdateFileResponseType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session has been closed, or, in case of a backward flow, if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
fmsVaultToken (PlmFMSVAultToken, optional (delete old file))
PlmFMSVaultToken containing all attributes to contact the File Server via FMS Java daemon.
vaultName (String required)
vaultType (String, required)
vaultKind (String, required)
vaultNode (String, required)
vaultNetRef (String, required)
vaultPath (String, required)
fmsJadeNode (String, required)
fmsJadePort (String, required)
url (String, required)
tokenTimestamp (String, required)
token (String, required)
fmsTokens (PlmFMSToken, optional (delete old file))
PlmFMStoken containing all attributes to contact the File Server via FMS Java daemon.
id (String, required)
Document to File relation Record CID
parentId (String, required)
Document to File relation Record Parent CID (Document CID)
childId (String, required)
Document to File relation Record Child CID (File CID)
sourceFileToken (PlmFMSFileToken, optional)
targetFileToken (PLMFMSFileToken, required)
fileInfo (DFMREsultData, optional)
id (String, required)
Document to Document relation Record CID.
parentId (String, required)
Document to Document relation Record Parent CID (Document CID.
childId (String, required)
Document to Document relation Record Child CID (Document CID
attributes (List<PlmAttributeChoice>, required)
The following are the bulk operation names of the single request operations for DocumentManagement Web Services describing the concurrent sections:
getFiles(Bulk)
createUpdateFileObject(Bulk)
getFMSVault(Bulk)
Service
To get a list of files assigned to a specific document.
Usage
The operation uses the document file relation mask that is specified in the request to retrieve the data (search in mask).
The response provides the necessary data to call the downloadFile Web Service and is divided into the following parts:
List of Vault definitions including:
FMS Server definition
FMS Java Daemon definition
FMS Vault Tokens
List of FMS File Tokens including (in-case of replication, the source file and target file are filled if not only the target file):
Source File with file tokens
Target file with file tokens
List of Files
By default the response returns values of all visible document file relation fields (plus some important ID fields like EDB_ID and C_ID) that are contained in the mask. Response information can be restricted by defining the list of fields that must be returned, but note that you can only return values for fields which are available in the mask.
The settings of the mask determines the sorting of the data.
Return values are provided in a standardized format as marshaled by the JAXB framework. Date values are in UTC, based on the assumption that the data returned by the EDM server is in server local time.
By default, only the current language value is retrieved for multi-lingual fields. However, the Web Service client can request to retrieve all language values in the same call.
The method fills a list of Vault in the form of PlmFMSVaultToken in the response, which is referenced in one or many from the PlmFMSTokens.
The file tokens in the form PlmFMSTokens in the response contains file details and its generated access tokens. Each file token represents one file from the file list and can be referenced by doc_fil ID.
Request Type
GetFilesRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmDocumentFileQuery (PlmDocumentFileQuery):
| document (PlmObjectRef, required) | The PLM document object as PlmObjectReference. |
| documentFileMaskName (String, required) | The document file relation list to use for the query. |
| selection (List<PlmCondition>, required) | List of PlmConditions which contain the field name/value pairs to search for document records. |
| ignoreRecordLimit (Boolean, optional, default=false) | A flag indicates if the record limit must be ignored. |
| excludeVaultValues (Boolean, optional, default=true) | A flag indicates if the vault values must be returned, too. |
| attributeNames (List<String>, optional) | inherited from PlmResult |
| includeBinaryValues (Boolean, optional) | inherited from PlmResult |
| includeAllLanguages (Boolean, optional) | inherited from PlmResult |
Response Type
GetFilesResponeType
messageId (String, required)
messageName (String, required)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
recordLimitHit (boolean, required)
[true | false] Indicates if the query result has hit the mask limit.
url (String, optional)
The URL to the createUpdateFileObject web service.
fmsVaultTokens (List<PlmFMSVaultToken>, optional)
List of PlmFMSVaultToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSVaultToken |
|
fmsTokens (List<PlmFMSToken>, optional)
List of PlmFMSToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSToken |
|
objects (List<DFMResultData>, required)
List of Document File relation record found.
| DFMResultData |
|
The created objects contain the attributes listed in the request.
In case one or more of the requested attributes do not exist, PARTIAL_SUCCESS is returned.
In case one or more of the requested attributes are not accessible, a WARNING is returned.
If no attributes have been requested (attribute list is missing), the whole object including all visible attributes and the ID attributes (EDB_ID and C_ID) are returned. If none of the requested attributes exists or the list is empty, only the ID attributes (EDB_ID and C_ID) are returned.
Service
This operation retrieves upload information for different types of documents, Cax, file and creation systems, or for the given Vault name used. (applies whether DFM is active or not).
Usage
The Web Service client provides the different needed combinations as request and gets the information for the upload of the different combinations.
Request Type
getFMSVaultRequestType
messageId (String, optional)
messageName (String, optional)
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
document (PlmObjectRef, optional): An object reference to the document (the parent)
fileFormat (String, optional)
stepCreationSystem (String, optional): The Step Creation System
vaultName (String, optional): The Vault name for which the details are to be retrieved
Response Type
getFMSVaultResponseType
messageId (String, required)
messageName (String, required)
statusCode(ResponseStatusCode, required)
SUCCESS, PARTIAL_SUCCESS, WARNING, or FAILURE
exceptions (List<PlmExceptionType>, optional)
List of exceptions that occurred during the operation.
warnings (List<PlmWarningType>, optional)
List of warnings that occurred during the operation.
ticket (String, optional)
The PLM ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
url (String, required)
The URL to the createUpdateFileObject Web Service.
fmsVaultToken (PlmFMSVaultToken,required)
PlmFMSVaultToken containing all attributes to contact the File Server via FMS Java daemon.
| PlmFMSVaultTokent |
|
The Metadata Service enables you to read the definition of Agile e6 classes like entities, entity types, and relations.
All operations need one request object as input and return one response object.
The request contains at least the name of Agile e6 class and a mask name.
The response contains the metadata of the respective Agile e6 class.
Bulk operations allow you to execute a whole list of requests with one Web Service call. The response of a bulk operation contains a list of responses matching the list of requests.
The Agile e6 metadata is read from Agile e6 using the mask specified in the request.
It is only possible to access Agile e6 attributes that are visible in this mask, with the exception of the ID fields EDB_ID and C_ID.
Only masks listed in the so called Web Service Whitelist of Agile e6 can be accessed.
The following are the bulk operation names of the single request operations for Metadata Web Services describing the concurrent sections.
getEntity(Bulk)
getEntityType(Bulk)
getEntityRelation(Bulk)
getNumberCycles(Bulk)
getNumbers(Bulk)
Service
To get the metadata of an Agile e6 entity.
Usage
The data is based on the mask used to access the data. If the request does not pass a specific mask name, the default mask of the entity is used. The response contains the definition of all visible attributes in the mask. If an attribute has mode specific access, it is returned regardless of the mode specific access value.
Request Type
GetEntityRequestType
name (String): The entity name.
mask (String): The mask name to use to read this entity (optional).
If empty, the default list of the entity is used.
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetEntityResponseType
statusCode (ResponseStatusCode): SUCCESS or FAILURE.
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
entity (PlmEntity): contains the entity definition (all information is returned with type String, unless noted otherwise):
|
||
|
|
|
|
|
|
|
||
|
|
|
|
|
Service
To get the metadata of an Agile e6 entity type.
Usage
The data is based on the mask used to access the data. If the request does not pass a specific mask name, the default mask of the entity type is used. The response contains the definition of all visible attributes in the mask. If an attribute has mode specific access, it is returned regardless of the mode specific access value.
If the mask contains visible multi-lingual attributes, all generated invisible multi-lingual attribute siblings are returned.
Request Type
GetEntityTypeRequestType
name (String): the name of the master entity for this type.
type (String): the name of the type.
mask (String): The mask name to be used to read this entity (optional).
If empty, the default list of the entity is used.
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetEntityTypeResponseType
statusCode (ResponseStatusCode): SUCCESS or FAILURE.
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType)) that occurred during the operation.
An entity type definition of type PlmEntityType (all information is returned with type String, unless noted otherwise):
|
||
|
|
|
|
|
|
|
||
|
|
Service
To get the metadata of an Agile e6 constraint, refine, or aggregate relation.
Usage
The data is based on the mask used to access the data. If the request does not pass a specific mask name, the default mask of the entity is used.
The response contains the definition of all visible attributes in the mask. If an attribute has mode specific access, it is returned regardless of the mode specific access value.
In addition, the response contains the default ID fields of the relation (EDB_ID and C_ID, if available), even if these are invisible.
If the mask contains visible multi-lingual attributes, all generated invisible multi-lingual attribute siblings are returned.
Request Type
GetEntityRelationRequestType
metaRelation (PlmMetaRelation): Describes the relation to be read, and must contain at least the following information:
| parent: | The name of the parent entity (e.g. "EDB-ARTICLE") |
| child: | The name of the child entity (e.g. "EDB-DOCUMENT") |
| type: | The relation type (e.g. PlmRelationTypeEnum.REFINE) |
| view: | The name of the view. (e.g. "STR") |
The meta relation object can either be taken from the response of a call to getEntity/getEntity type, or it can be created using hard coded default values. The four attributes listed above are needed to identify the relation data, the rest of the attributes in PlmMetaRelation are not relevant.
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetEntityRelationResponseType
statusCode (ResponseStatusCode): SUCCESS or FAILURE.
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
plmRelation (PlmRelation): The relation definition containing:
|
||
|
|
|
|
|
|
|
This operation is used to retrieve several number cycles which are used in a mask of an entity or a relation.Service
Usage
The operation scans the field default definition in the mask and returns the number cycle names. The operation considers field defaults as well as mask specific field defaults. The Web Service returns number cycles from visible fields only, because invisible fields cannot be populated with a number cycle number returned by getNumber Web Service
Request Type
GetNumberCyclesRequestType
plmClass (PlmClassRef)
The class definition containing the entity and a mask name (optional).
|
Note: Leave it empty to read a relation mask, metaRelation is used in this case. |
metaRelation (PlmMetaRelationRef)
The relation definition including parent and child entity, relation type, view, and mask name (optional).
|
Note: Leave it empty to read an entity mask, plmClass is used in this case. |
messageId (String)
ID to be returned in the response (optional).
messageName (String)
Name to be returned in the response (optional).
sessionTicket (String, optional)
The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetNumberCyclesResponseType
statusCode (ResponseStatusCode):
SUCCESS or FAILURE.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
numberCycles (List<PlmFieldNumberCycle>)
The list of all number cycles used in this mask, consisting of field name and number cycle name.
Service
This operation is used to get one or more numbers generated by a number generator. Number generators are used to create instance object IDs. The format of the number can be defined in a flexible way by defining the numbering template.
Usage
|
Note: It is not possible to hand back unused numbers, once the numbers have been retrieved. Thus, it is important to use this Web Service carefully; otherwise the number cycle might run out of range. |
In order to control which number cycles are available for the Web Service call "getNumbers", field "Max # of Numbers per Web Service" is available. If the value is "0" or NULL, the number cycle is not accessible for the Web service, else the value defines how many numbers (<=) can be generated by one getNumbers Web Service call.
Request Type
GetNumbersRequestType
messageId (String)
ID to be returned in the response (optional).
messageName (String)
Name to be returned in the response (optional).
sessionTicket (String, optional)
The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
numberCycleName (String)
The name of the number cycle to be used.
Range (Integer)
The amount of numbers to be requested from the number server.
Response Type
GetNumberCyclesResponseType
statusCode (ResponseStatusCode): SUCCESS, PARTIAL_SUCCESS, WARNING or FAILURE.
| SUCCESS | Object deleted successfully. |
| PARTIAL_SUCCESS | Is returned when all numbers are generated, but threshold warning is issued (number variant will be exhausted soon). |
| WARNING | Is returned with a list of only some of the requested numbers that are generated. Reasons are that number variant is exhausted after generating a few numbers or that more numbers than allowed were requested for one Web Service call. |
| FAILURE | Is returned when the number variant is not found, has the wrong format (missing #), when the Web Service is not enabled, exhausted, or the definition for the number variant is incorrect. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings (List< PlmWarningType >): List of warnings that occurred during the operation.
exceptions (List< PlmExceptionType >): List of exceptions that occurred during the operation.
numberCycleName (String): Name of the number cycle, copied from the request.
numbers (List<String>): List of numbers returned from this number cycle.
The Configuration Web Service enables you to retrieve PLM objects from Agile e6. It retrieves configuration data of a PLM object, such as Default, User Context, etc., specified by its name.
The requests include the value(s) for specifying the requested object. Responses include the requested objects.
Bulk operations require a list of requests to execute. These return with a list of responses.
The following are the Web Service operation names of the single request operations for Configuration Web Services describing the concurrent sections.
getUserContext
setUserContext
Service
To get all the information of the current user context of an Agile e6 session.
Usage
The request object carries current Agile e6 user's details and only an optional message ID and name. The response object delivers the user attributes, all group assignments attributes, current view (Released, Global etc.), current context (DSG, ENG), current project assignment (Project ID) and current Org assignment (Org ID).
Request Type
GetUserContextRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetUserContextResponseType
statusCode (ResponseStatusCode): SUCCESS or FAILURE.
| SUCCESS | All objects from user context are returned, if they are available.
There could be some warnings in the message block, if some objects (e.g. currentJob, currentRole) are not available. It could make sense for setUserContext, but it is not necessary to check for getUserContext. |
| FAILURE | There was a connection problem. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the PLM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
plmUserContext (PlmUserContext):
| plmUserInfo (PlmUserContextUserInfo): |
|
| plmViewInfo (PlmUserContextView): |
|
| plmChangeManagementInfo (PlmUserContextChg): |
|
| plmMoaMpaInfo (PlmUserContextMoaMpa): |
|
| plmDFMInfo (PlmUserContextDFM): |
|
Service
To modify one or more settings of the current user context in the current Agile e6 session.
Usage
This operation is used to set current job in MOA/MPA environment. The request object carries the user context details, such as the new view, new assignment, new organization assignment, and new project assignment. The response object delivers the user attributes, group assignments, new current view, new current context, new current project assignment, new current org assignment.
Request Type
SetUserContextRequestType
messageId (String): ID to be returned in the response.
messageName (String): Name to be returned in the response.
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
plmUserContext (PlmUserContext):
| plmUserInfo (PlmUserContextUserInfo): |
|
| plmViewInfo (PlmUserContextView): |
|
| plmChangeManagementInfo (PlmUserContextChg): |
|
| plmMoaMpaInfo (PlmUserContextMoaMpa): |
|
| plmDFMInfo (PlmUserContextDFM): |
|
Response Type
SetUserContextRequestType
statusCode (ResponseStatusCode): SUCCESS. PARTIAL_SUCCESS,or FAILURE.
| SUCCESS | All objects could be set successfully; some objects could not be set with warnings. |
| PARTIAL_SUCCESS | Some objects could be set successfully, while some could not be set with warnings. |
| FAILURE | There was a connection problem. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings: List of warnings (PlmWarningType) that occurred during the operation.
exceptions: List of exceptions (PlmExceptionType) that occurred during the operation.
plmUserContext (PlmUserContext):
| plmUserInfo (PlmUserContextUserInfo): |
|
| plmViewInfo (PlmUserContextView): |
|
| plmChangeManagementInfo (PlmUserContextChg): |
|
| plmMoaMpaInfo (PlmUserContextMoaMpa): |
|
| plmDFMInfo (PlmUserContextDFM): |
|
The following are the bulk operation names of the single request operations for Configuration Web Services describing the concurrent sections.
getDefault(Bulk)
createDefault(Bulk)
Service
To get the contents of a PLM Default value.
Usage
It is possible to read all available defaults from system configuration.
Request Type
GetDefaultRequestType
defaultName (String):
Name of the DataView default.
messageId (String):
ID to be returned in the response (optional).
messageName (String):
Name to be returned in the response (optional).
sessionTicket (String, optional)
The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
Response Type
GetDefaultResponseType
Status Code
| PARTIAL_SUCCESS | Typed default value is NULL |
| FAILURE | Default "Non-existent" - PLM Object is NULL~ |
PLM Default as complex data type (String, Integer, Float, Boolean)
Service
This operation creates/updates the content of a PLM Default value.
Usage
Similar to the corresponding ECI function "eci_add_dfv", the Web Service does not persist the default value. Thus, a default value set via createDefault will exist only at runtime and for the current Web Service session.
|
Note: The Web Service allows creating defaults for the current user only. |
It is possible to create/update any defaults in system configuration.
Request Type
CreateDefaultRequestType
messageId (String):
ID to be returned in the response (optional).
messageName (String):
Name to be returned in the response (optional).
sessionTicket (String, optional)
The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
PLM Default as complex data type (String, Integer, Float):
Compared to getDefault and createDefault, it only supports String, Integer, and Float as input values.
The format for other types is not defined by DataView, and the value is always stored as String.
Response Type
GetDefaultResponseType
Status Code
| SUCCESS | The default is created. |
| PARTIAL_SUCCESS | Typed default value is NULL |
| FAILURE | Default "Non-existent" - PLM Object is NULL~ |
ticket (String,): A PLM ticket. PLM Default as complex data type (String, Integer, Float, Boolean)
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): Copied from the request, or generated.
messageName (String): Copied from the request, or the operation name.
warnings (List< PlmWarningType >): List of warnings that occurred during the operation.
exceptions (List< PlmExceptionType >): List of exceptions that occurred during the operation.
Agile e6 ECService Web Services are a set of Business Services that supplement EDM's Core Web Services.
Example:
Below are examples given of how CAD scenarios are used to describe the generic character of the createUpdateStructure Web Service operation.
This operation allows you to process relations like Create/Read/Update/Delete between the following objects:
Document - Document
Document structure (STR):
The document structure is used in the context of CAD integration to represent the assembly structure (top-level-assembly -> sub-assembly -> single part).
Snapshot structure (SNP):
The Snapshot structure allows saving specific document structure configurations, independent from the version view setting. Furthermore, it is used to store design variants in Agile e6. The CAD system has full control of the Snapshot structure. The CAD system is the only authoring system creating Snapshot structures.
Intern-Extern Relationship (IER):
CAD assemblies sometimes make use of external references. For instance, if an engineer is designing a tool to manufacture the work piece, he is using the work piece geometry to derive the tool geometry. In order to assign the work piece geometry to the tool assembly structure, the Intern-Extern Relationship is used.
Document - Item (STR Structure)
Optional use case: Is used if items are derived from CAD structure.
Item-Item (STR Bill of Material)
Optional use case: Is used if BOM is derived from CAD structure.
Filtering
Document-Document STR relations, which are created/owned by the CAD integration, can be identified by the field T_DOC_STR.UG2_IDENT. "UG2_IDENT" contains a name which indicates the source CAD integration. If the relation record is owned by the CAD integration, and the access rights of the relation record allow deletion, the CAD integration is allowed to delete the record. In other words, if the relation record was created manually by a user, the CAD integration shall never delete such a record. The UG2_IDENT mechanism is also used for BOM and Item-Document relation.
In general, the Web Service shall allow defining a set of field value pairs which are used to identify objects that are managed by the CAD integration. It is possible to define separate sets of field value pairs for the different relation (BOM, Item-Document, Document-Document).
|
Note: You can use wildcards to specify filter criteria. |
In order to find out if data records need to be created, updated, or deleted, an additional comparison pattern can be defined. For the CAD document structure the comparison pattern typically consists of the following attributes:
Parent-ID(C_ID_1)
Child-ID (C_ID_2)
Transf.-Matrix (ECC_XMAT)
Old Filename (CAX_COM)
Structure Ref (CAX_REF)
CAX-internal value (CAX_04)
This list of attributes is configurable. It is possible to define separate list of fields for the different relation types (BOM, Item-Document, Document-Document, Document-File).
If the record, defined by the values of the comparison pattern, already exists in Agile e6, the record is updated. Otherwise, it is created. Remaining records, which are not listed in the Web Service, but are owned by the CAD integration (see UG2_Ident above), are deleted in Agile e6. Records which are not owned by the CAD integration remain untouched. If updating or deletion fails due to insufficient access rights, the Web Service reports an error.
Scenarios
The scenario below illustrates the basics of structure update.
|
Note: It focuses on the document structure only. |
Sample Data: CAD Document Structure (Pre-Update)
Sample Data: CAD Document Structure (Post-Update)
Create
The create use case is executed if a relation record cannot be found in Agile e6 while comparing the comparison pattern attributes.
Read
Reading of data is part of the create/update use case, as create/update returns the attribute values of created/updated records.
Update
In the CAD document structure context, the update is always executed with a delete and a create operation. Thus, all data is first deleted and then newly created.
However, in the BOM, and maybe in the Item-Document relation, too, the PosNo information is significant and the approach of deleting and recreating does not work. Hence, the update use case is required.
Delete
The delete operation is implicitly used as part of the update of a CAD document structure. Additionally, the delete use case applies if a structure contains spare records in Agile e6. However, this behavior is optional for an object type level.
For instance, there are use cases where the CAD integration loads only part of the CAD assembly structure and hence saves only part of the CAD structure back to Agile e6. By setting the delete option for every object type appropriately, the deletion of alleged spare records is omitted.
|
Note: In case a complete structure needs to be deleted, it is initiated by sending an empty structure. |
Document-Item-BOM Scenario
Sometimes, not all document structure nodes make it into an item node and the Web Service ignores this. The input parameter structure for the Web Service clearly defines which item structure needs to be created.
Generic Systematic
Comparison fields (see green and blue columns in graphic below)
Defines the list of fields which are used to identify a specific record in the old Agile e6 data structure (see also graphic above)
CAD Structure
Shows the new structure as maintained in the CAD system.
Old Agile e6 structure
Represents the structure as it is stored in Agile e6 before the update
New Agile e6 structure
Represents the structure as it will be stored after the update
"CAD Context" (red column):
Defines the field value pair(s), which is/are used to identify all records that are managed by the CAD integration. Cells with grey fill color are not managed by the CAD integration.
|
Note: Record 4|4|4|4 will only be deleted if the delete flag for the specific relation type is set to true. |
Access Control
The access control can be applied on different levels.
For "update"/"delete" use case the Agile e6 access rights define if the write and/or delete access is available for the object and for the current user.
Especially in the "create" use case, the parent access might be considered. If current user has write or delete access to the parent record, he is allowed to create/update/delete the relation record.
Specific for documents: The modification of references to files and sub-documents might require the parent document to be "reserved" by the current user.
The first two cases will be handled by the widget, which is used in the Web Service to create/update/delete the relation objects. Specific triggers at the form/widget assure you that the checks will be performed. Customer specific checks can be included by adding specific userexits.
It might be sufficient to add a trigger at the forms to check if the parent document is reserved by the current user. However, it might be better to control the behavior with Web Service parameters for specific relation types (e.g. reservation of parent document required in general to create/update/delete the file assignment), or even on relation record level.
Error Handling
While creating/updating/deleting relation records, the following issues can appear:
A unique index violation during create/update, because a duplicate record will be created.
The parent and/or child record is not available (either does not exist at all, or is not accessible).
The user has no access to write and/or delete.
Any other relation object trigger throws an error.
In case of an error, the processing of the remaining relation objects continues. At the end, the Web Service reports which objects failed to be created/updated/deleted, together with a corresponding error message.
To ensure that only masks designed for Web Service access are used, all mask names are checked against a Whitelist that is maintained by the administrator of the Agile e6 installation.
Service
This Web Service operation allows you to process relations like Create/Read/Update/Delete and many more between the following objects:
Document - Document
Document - Item (STR Structure)
Item-Item (STR Bill of Material)
Usage
This single request operation for ECService Web Services describes the generic character of the Web Service.
Request Type
CreateUpdateStructureRequestType
messageId (String): ID to be returned in the response (optional).
messageName (String): Name to be returned in the response (optional).
sessionTicket (String, optional): The PLM session ticket to use for this request, if it has not been passed as user credentials in the HTTP header.
relationType (List<ECRelationDescriptor<): List of relations to process.
| contextFilter (List<PlmCondition) | CAD Context filter: attribute names (For example: UG2_IDENT) and values. This is used to query for the relation records of the parent in the Agile e6 relation list. |
| comparisonPattern (List<String>) | List of attribute names used as comparison pattern for relation record identification.
Comparison pattern (e.g. Parent-ID, Child-ID, Transf.-Matrix, Old Filename, Structure Ref, CAX-internal value) |
| cleanupFlag (Boolean) | Defines if records not matching any relation object are deleted. |
| Relation (PlmMetaRelationRef) | The metadata of the relation to be read (parent, child, type, view). This allows specifying the aggregate, refined, constraint, or type relation. |
| Structures (List<ECStructure>) | List of parents and their relation objects.
parentId (PlmAttributeChoice): Unique ID of the parent (EDB_ID or C_ID). data (List<ECData>): The relation data for this parent. If the list is empty and cleanup is requested, all relation records found in the CAD context are deleted. Otherwise, the comparison algorithm checks which records need to be created, updated, or deleted from the EDM server. attributes (List<PlmAttributeChoice>: List of attribute values to use for updating or creating the relation record. This must contain the attribute CHILD.C_ID if a create operation is required. |
plmResult(plmResult): This describes how the result of the operation is returned to the client.
| attributeNames (Boolean) | List of field names to be returned |
|
| includeBinaryValues (Boolean) | Include binary values |
|
| includeAllLanguages (Boolean) | Include all languages |
|
Response Type
CreateUpdateStructureResponseType
statusCode (ResponseStatusCode):
| SUCCESS | The newly created PLM object including all attributes defined by the PLM result of the request. |
| PARTIAL_SUCCESS | The newly created PLM object including some of the attributes defined by the PlmResult of the request. |
| FAILURE | A faulty description including an error message and the type of error. |
ticket (String): A PLM ticket.
The ticket can be used instead of the password in subsequent calls. It allows the client to reference the Agile e6 session, even if the HTTP session is closed, or (in case of a backward flow) if there is no HTTP session.
The ticket is only valid for the EDM server instance that generated it.
messageId (String): copied from the request, or generated.
messageName (String): copied from the request, or the operation name.
warnings (List<PlmWarningType>): List of warnings that occurred during the operation.
exceptions (List<PlmExceptionType>): List of exceptions that occurred during the operation.
relations (List<ECRelationData>): Data with error/success flag, plus error message (if available). The content and order in the list correspond to the list of ECRelationDescriptors in the request:
| List<ECResultStructure> | parentId (PlmAttributeChoice): Unique ID of the parent (EDB_ID or C_ID)
warnings (List< PlmWarningType >): List of warnings that occurred when processing this structure (optional). exceptions (List< PlmExceptionType >): List of exceptions that occurred when processing this structure (optional). This contains the information about failed delete attempts if structure cleanup was requested |
resultData (List<ECResultData>): List of structure elements for this parent. It contains all updated or created relation objects.
|
