http://server:8181/enovia/jaxrs/service
23 June 2016
RESTful web services are created with XML configuration files. The services are used to expose information available in ENOVIA.
The base URL for services are (by default):
http://server:8181/enovia/jaxrs/service
The example above uses the default context path /enovia/jaxrs. This path may be different in your environment since it can be configured. See the next chapter for more information how to change this. |
A list of available services can be retrieved by accessing the base URL. Services are listed in JSON format. Example using cUrl:
curl -X GET http://server:8181/enovia/jaxrs/service
Every service has a unique service name which is used when accessing it.
For example, a service with the name part
is available on:
http://server:8181/enovia/jaxrs/service/part
Any information after the service name in the URL is interpreted as PathParameters. Example of URL using PathParameters:
http://server:8181/enovia/jaxrs/service/part/Resistor/1200-0001/1
By default, the context path to the REST applications is /enovia/jaxrs/.
Within the file ${TIF_ROOT}/modules/enovia/etc/modules.custom.properties
,
this can be changed using the property below.
http.webapp.jaxrs.contextPath = /enovia/jaxrs ^^^^^
As an alternative you could also change the path for all applications by using the below example.
http.webapp.contextPath.default = /tif/%2$s
The %2$s
refers to the name of the webapp folder.
<Rest>
<DisplayName>Part</DisplayName>
<ServiceName>part</ServiceName>
<IdLocator type="tnr">
<AllowWildcards>false</AllowWildcards>
</IdLocator>
<Read payload="tvc:payload:tix/PartData.xml" />
<Events>...</Events>
</Rest>
Configuration files are stored in the folder restservice
. The root element of
the XML file is <Rest>
. The available child elements are listed in the table
below.
Element | Description | Mandatory |
---|---|---|
|
User friendly name of the service. Used for instance the Admin UI. |
No, but recommended. |
|
Defines the name of the service. It is used by clients to access the service. The name must be unique across all services. It may only consist of alfanumerical characters and forward slashes (/). |
No |
Defines how to find the object/s the client is interested in. Read more in the IdLocator chapter. |
No |
|
Defines how to read data. Read more in the Read Operation chapter. |
Yes |
|
See page Job Events for details. |
No |
|
Defines the credentials that will be used when running the REST service. Read more in the Credentials chapter. |
Yes. |
|
|
Defines the type of transaction to use while running the REST service. The possible values are:
|
No. An inactive (no transaction) is used. |
|
May be used to define additional access rules on the REST service. Example; only allow this REST service to operate on objects in a particular state, or in a particular vault. Or, restrict access to users assigned to a particular role or group. Read more in the Access chapter. |
No. |
If the <ServiceName>
element is omitted, the name of the service is calculated based on its location in the filesystem.
For example, if a RestService is stored in the folder cfg/restservice/foo/bar/test.xml
then its service name / path is calculated to foo/bar/test
.
And in case a RestService is stored in the folder cfg/restservice/part-data.xml
then its service name / path is calculated to part-data
.
Client sends HTTP request. The request include information about which service that is of interest along with addtional PathParameters/QueryParamters.
The RESTful web services corresponding to the request is located. TIF maintains a registry of all configurable services.
Optional: The IdLocator is executed. It is responsible for finding the object the client is requesting based on the PathParamters/QueryParameters.
The operation is executed. For example, extracting information for the Part found by the IdLocator.
The response is sent back to the client.
The <Credentials>
element contains the following attributes:
A boolean value. Specifies if authentication is carried out via the servlet container. See chapter below how to configure this.
A string value. Defines the name of the ENOVIA™ user that we will run the service as.
A boolean value. Useful together when containerManaged=true
and
you want to run the service as a super user, while authentication is required.
Valid child elements are defined in the table below
Element | Description | Mandatory |
---|---|---|
|
Used for defining the ENOVIA/3DExperience security context. See below how to configure this. |
No |
|
In case container managed authentication is enabled, you may define additional roles, which the authenticated user must have in order to gain access. These roles are typically not ENOVIA/3DExperience roles, in case of Kerberos authentication these will be roles from your Active Directory. Note that if you specify multiple roles, the user is only required to have one of the listed roles in order to get access. Example below:
|
No. |
|
Specify additional ENOVIA/3DExperience assignments the user must have in order to proceed. Example below:
|
No |
Via the <SecurityContext>
element you define what security context to use.
You may do the following.
Point out a mapping file
Or use a default mapping file
Specify a named security context
Or use the "default" security context as configured for the ENOVIA user
To point out a mapFile use the syntax below.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext mapFile="sec-mapping.xml" />
Use the default mapping file.
The default file is specified via the property securityMapping.defaultFile
, and the default value is security-context-mapping.xml
.
The file is relative to ${TIF_ROOT}/modules/enovia/etc
|
<SecurityContext useDefaultMapFile="true" />
The format of the mapping file is shown below:
<Contexts>
<Context name="Design Engineer.Company Name.GLOBAL">
<User is="user1" />(1)
<User is="user2" />
<User is="user3" />
<Role is="engineer" /> (2)
<Role is="designer" />
<Parameter name="test" is="something" /> (3)
<Parameter name="x" is="y" />
</Context>
<Context name="...">...</Context>
<Context name="...">...</Context>
</Contexts>
NOTE that specifying user and role requires having enabled container managed authentication (Kerberos or Basic Authenticaton etc.)
1 | Specifies certain users to match against |
2 | Specifies additional roles the user should have |
3 | Specifies additional parameters and value to be evaluated In case of a REST service, the parameters are the request parameters passed to the service. |
The evaluation logic is:
User list is EMPTY or user is in list
Role list is EMPTY or user have one of the roles in the list
Parameter list is EMPTY or one of the parameters have the expected value
If A AND B AND C is satisfied, then use the security context defined for this "rule".
To use a specific Security Context:
<SecurityContext use="Design Engineer.Company Name.GLOBAL" />
Specify using the default security context.
<SecurityContext useDefault="true" />
You can enable security on the servlet container level and either use Kerberos/SPNego authentication OR use Basic authentication and authenticate against the ENOVIA™ database.
Within the ${TIF_ROOT}/modules/enovia/etc/module.custom.properties
, you need
to specify what login service to be used including its realm and optionally some
extra parameters.
The login services currently supported are
A login service that will authenticate the remote user against the ENOVIA™ database.
A login service that will authenticate the remote user against a LDAP directory (for example Active Directory)
A login service supporting Single Sign On against Active Directory.
In order to use Spnego authentication, also read this document in order to setup the core parts of Spnego/Kerberos. |
If the "loginService" is set to "ldap", TIF will authenticate users against a LDAP directory.
http.webapp.jaxrs.loginService=ldap
http.webapp.jaxrs.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
There are some additional LDAP settings required to be defined. You can specify global LDAP parameters and/or web application specific LDAP parameters. In most cases you will be fine with only global LDAP settings.
For convenience, the application specific parameters will be merged with the global LDAP parameters. Hence you only need to override/define the parameters that is different on the application level.
Please see the table below.
The global parameter name is ldap. , while the application specific parameter
are named like http.webapp.<APP_NAME>.ldap.
|
Parameter | Description | Required |
---|---|---|
ldap.server |
Defines the server or list of LDAP servers. Separate with space if using multiple. |
Yes |
ldap.rootDN |
Defines the root dn, where all LDAP searches starts from. If we can start a search starting at a sub-node (as opposed to root), you get a better performance because it narrows down the scope of a search. This field specifies the DN of such a subtree. |
No |
ldap.userSearchBase |
The relative DN (From the root DN) that further narrow down searches to the sub-tree. If you do specify this value, the field normally looks something like "ou=people". |
No |
ldap.userSearchFilter |
This field determines the query to be run to identify the user record. The query is almost always "uid={0}" as per defined in RFC 2798, so in most cases you should leave this field empty and let this default kick in. If your LDAP server doesn’t have uid or doesn’t use a meaningful uid value, try "mail={0}", which lets people login by their e-mail address. If you do specify a different query, specify an LDAP query string with marker token "{0}", which is to be replaced by the user name string entered by the user. |
Yes |
ldap.groupMembershipAttribute |
If the user entry in the LDAP tree contains an attribute with the group membership, then specify that attribute here. Otherwise we need to query for the groups a user belongs to. |
Either this or the groupSearchBase / groupSearchFilter needs to be defined. |
ldap.groupSearchBase |
This field determines the query to be run to identify the organizational unit that contains groups. The query is almost always "ou=groups" so try that first, though this field may be left blank to search from the root DN. |
Not needed, but if the groupMembershipAttribute is undefine you can use this to make the group query faster. |
ldap.groupSearchFilter |
Defines the search filter for groups. In case we need to search the LDAP tree for group membership this needs to be defined. The marker token "{0}" is replaced with the current user’s DN. Example:
|
Yes unless groupMembershipAttribute is defined. |
ldap.managerDN |
If your LDAP server doesn’t support anonymous binding, then we would have to first authenticate itself against the LDAP server. A DN typically looks like CN=MyUser,CN=Users,DC=mydomain,DC=com although the exact sequence of tokens depends on the LDAP server configuration. It can be any valid DN as long as LDAP allows this user to query data. |
Probably Yes |
ldap.managerSecret |
The password for the manager DN |
Probably Yes |
ldap.displayNameLDAPAttribute |
The attribute holding the display name. Per default we use the CN of the user entry. |
No |
ldap.emailAddressLDAPAttribute |
The attribute holding the email value. Per default we use the field This field is currently not used so you can leave it blank. |
No |
ldap.pooled |
Whether or not to pool the LDAP connections |
No |
Example setup below for Active Directory.
ldap.server=ldapserver.yourdomain.com:3268
ldap.rootDN=DC=yourdomain,DC=com
ldap.managerDN=CN=nameofuser,CN=groupforuser,DC=yourdomain,DC=com
ldap.managerSecret=the_very_secret_string
ldap.userSearchBase=
ldap.userSearchFilter=(&(objectClass=person)(|(sAMAccountName={0})(userPrincipalName={0}@*)))
ldap.emailAddressLDAPAttribute=mail
ldap.displayNameLDAPAttribute=displayName
ldap.groupMembershipAttribute=memberOf
#ldap.groupSearchBase=OU=groups
#ldap.groupSearchFilter=(&(member={0})(objectClass=group))
The managerSecret value can either be defined in plain text, or you can encrypt the password from an MQL client using the "mql encrypt" feature.
The encrypted value can be used in the configuration file if you add the prefix Eg.
|
If the "loginService" is set to "enovia", TIF will authenticate users against the ENOVIA database.
http.webapp.jaxrs.loginService=enovia
http.webapp.jaxrs.realm=Webservices
The second value defines the "realm". (See https://www.ietf.org/rfc/rfc2617.txt for more information about realms and basic authentication).
Secondly, an example for spnego:
http.webapp.jaxrs.loginService=spnego
http.webapp.jaxrs.spnego.targetName=HTTP/tifserver.exampledomain.com
http.webapp.jaxrs.realm=Webservices
Instead of specifying the targetName you may instead point out a property file that holds that value under the key targetName. See below: |
http.webapp.jaxrs.loginService=spnego
http.webapp.jaxrs.spnego.config=${tif.home}/etc/kerberos/spnego.properties
http.webapp.jaxrs.realm=Webservices
The spnego.properties
defines the targetName like this:
targetName = HTTP/tifserver.exampledomain.com
Within the "web.xml" file (webapps/jaxrs/WEB-INF/web.xml) you need to setup the rules for the application.
If you have not started TIF, you will not find the web.xml file, instead
it will be found under webapps/jaxrs/WEB-INF/web.xml.template . Upon start, TIF
will copy over the template file unless the web.xml file is found.
|
Below is an example when using ENOVIA/Basic authentication and how such might look like.
Note that in this example, each user that is supposed to use the web-services must have the role "WS-Integration-User". Note that depending on login service used (ldap or enovia), the role is either a LDAP role or a ENOVIA role.
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>WS-Integration-User</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
Below is an example for Spnego:
<security-constraint>
<web-resource-collection>
<web-resource-name>blocked</web-resource-name>
<url-pattern>/service/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>EXAMPLEDOMAIN.COM</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>SPNEGO</auth-method>
<realm-name>Webservices</realm-name>
</login-config>
The access restriction can be defined based upon following:
Role Assignment
Group Assignment
Person (A named user)
Access Mask (Access mask for the current object)
Access Program (A JPO that evaluates the access rights)
Access Expression (MQL expression that evaluates the access)
The example below illustrates how you can construct the access restriction:
<Access>
<Role>role_FirstRole</Role>
<Role>role_SecondRole</Role>
<Group>group_SomeGroup</Group>
<Mask>modify,checkout</Mask>
</Access>
Or use an access program:
<Access>
<Program name="MyJPO" method="checkAccess"/>
</Access>
Or use an access expression:
<Access>
<Expression><![CDATA[owner == context.user]]></Expression>
</Access>
The expression will only be possible to utilize on service’s that operates on one (1) business object. If your service would use an ID locator that returns multiple objects, the expression has no affect. |
The IdLocator is responsible for locating the object the client is requesting. This is done by using the PathParameters and/or QueryParameters associated in the request. For example, the parameters includes type, name and revision of the object or interest.
There are a number of built-in strategies for locating the object. It is also possible to write a custom IdLocator.
IdLocators are optional. For example, a service returning all countries in the system does not require an IdLocator. |
Uses a dataset to locate the object/s. The PathParameters/QueryParameters and the requested mimetype is available when using parameterized datasets. More information about parameterized datasets is available in the TVC Core Admin Guide.
The first PathParameter is available with the key pathparam_0
, second one with
key pathpararm_1
and so on. The QueryParameters are available with the same
key as in the request to the service. The requested mime type uses the key mimetype
.
<Rest>
<ServiceName>product</ServiceName>
<IdLocator dataset="tvc:data/ProductInStateFinder.xml" />
...
</Rest>
<DataSet>
<LatestInState>
<State>$(pathparam_1,empty=false)</State>
<Query>
<NamePattern>
<Name>$(pathparam_0,empty=false)</Name>
</NamePattern>
<Limit>1</Limit>
</Query>
</LatestInState>
</DataSet>
tnr
3 (type/name/revision)
Uses type, name and revision to identify the object. A query is used in the background to find the matching object.
Name | Description | Default |
---|---|---|
AllowWildcards |
Defines if wildcards are allowed in the paramters. |
false |
Limit |
Maximum number of objects that can be found |
100 |
Where |
Where clause to use in query.
Example: |
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="tnr">
<Where>revision==last"</Where>
<Limit>1</Limit>
</IdLocator>
...
</Rest>
value
1 (value)
Identifies the object using a value on an attribute/basic. Uses a query in the background to find the matching object. For example, it can be a unique product number stored in an attribute.
Name | Description | Default |
---|---|---|
Limit |
Maximum number of objects that can be found |
100 |
Match |
Defines what attribute/basic to use to find the object of interest. This setting is mandatory. Example: |
|
Type |
Defines a type that object must be of. |
* |
Where |
Where clause to use in query. Example: |
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="value">
<Match>$<attribute[attribute_ProductId]></Match>
</IdLocator>
...
</Rest>
http://server-name:8181/enovia/jaxrs/service/product/9857847
objectid
1 (objectid)
Uses an object id to locate the object.
<Rest>
<ServiceName>product</ServiceName>
<IdLocator type="objectid" />
...
</Rest>
http://server-name:8181/enovia/jaxrs/service/product/1234.5678.9123.4567
Specify the qualified java class name in the attribute className
. The java class must implement the interface com.technia.tif.enovia.jaxrs.service.idlocator.IdLocator
.
/**
* Responsible for identifying objects requested by the client of a configurable
* REST web service.
*
* @since 2015.3.0
*/
public interface IdLocator {
/**
* Locates object id/s based on the provided input.
*
* @param ctx Information about this REST call
* @return The object id/s
* @throws IdLocatorException Thrown if problem occur. For example, if no
* object was found.
* @since 2015.3.0
*/
Collection<String> locateIds(ExecutionCtx ctx) throws IdLocatorException;
}
Implement the interface com.technia.common.xml.XMLReadable if your id locator support configuration settings.
|
The operation is the actual job to perform. For example, read information about an object.
The payload read operation extracts information from ENOVIA for the object/s. Note that object id/s only are available in case the REST service contains an IdLocator.
To read payload, configure attribute type
with value payload
.
In addition, specify a payload using the attribute payload
.
See page [Payload Definition] for details on how to define the payload definition.
<Rest>
...
<Read type="payload" payload="tvc:payload/Product.xml" />
</Rest>
The read operation supports generating content in XML or JSON format. The Accept
header is used to determine which format to use.
Accept Header Value | Description |
---|---|
application/xml |
Generates content in XML format. This is the default, if no format is specified. |
application/json |
Generates content in JSON format. |
To disable automatic payload transform based on the Accept
header, set attribute autoTransform
to false
.
<Rest>
...
<Read type="payload" payload="tvc:payload/Product.xml" autoTransform="false" />
</Rest>
It is also possible to define response content type explicitly in payload configuration. See Payload Definition. |
The file read operation can be used to extract files that are checked into an object. The extraction is done from one object per request. Therefore, exactly one object id is required. Object id is specified by an IdLocator.
To extract files, configure attribute type
with value file
. In addition, it can be configured with the following attributes which files should be included or excluded.
Attribute | Description |
---|---|
|
A comma separated list of file formats that should be used to include files. |
|
A comma separated list of file names that should be used to include files. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
A comma separated list of file names that should be used to exclude files. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Defines if the extraction result should be compressed into a ZIP file if the result contains only one file. If there are more than one file, the result will compressed into a ZIP file regardless of this setting. Use values "true" or "false". Default is "false", if not configured. |
|
Configures "Content-Disposition" header in the response. Valid values are Value Default is |
<Rest>
...
<Read type="file"
includeFormats="generic,zip"
includeFileNames="text*.txt,package*.zip"
excludeFileNames="*.doc"
zipOnlyFile="true"/>
</Rest>
Client may also add one or more request specific query parameters, that can be used to include or exclude files even more detailed per request. It should noticed that request specific filters cannot be used to extract files that configured filters do not allow. The following query parameters are supported.
Query Parameter | Description |
---|---|
|
File format that should be used. |
|
Name of file that should be included. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Name of file that should be exluded. Wildcards can be used. The wildcard matcher uses the characters '?' and '*' to represent a single or multiple wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-insensitive by default. |
|
Can be used to override default content disposition configuration. See previous table for details. |
Client may also pass a list of filters by using multiple parameters.
http://server-name:8181/enovia/jaxrs/service/product/Sales+Item/1200-1000/A?includeFormat=generic&includeFileName=*123.txt&excludeFileName=*.zip
The file update operation can be used to check in files to an object. Check in can be done to one object per request. Therefore, exactly one object id is required. Object id is specified by an IdLocator.
A request should be done with method "PUT" and using multipart/form-data encoding.
To check in files, configure attribute type
with value file
.
<Rest>
...
<Update type="file"
format="generic"
existStrategy="newversion"
append="true"
useCDM="true"
unzip="false" />
</Rest>
In addition, it should be configured with the following attributes how files are checked in.
Attribute | Description | Required |
---|---|---|
|
Defines what should happen if a file with same name is already checked in. Use value "fail" if the operation should cause the request to fail. Use value "overwrite" if file should be overwritten. Use value "newversion" if new version of file should be created. In this case attribute "useCDM" must be "true". |
Yes |
|
Defines in which format file is checked in. |
Yes |
|
Defines if file should be appended to the object. If "false", then other files in same format are removed from object. Use value "true" or "false". If disabled, attribute "useCDM" or "unzip" cannot be "true". |
No, default is "true". |
|
Defines if Common Document Model or CDM is applied. Use value "true" or "false". If enabled, attribute "append" cannot be "false". |
No, default is "false". |
|
Defines if zipped uploaded files are extracted and their contents are checked in instead. Files are retrieved from the root level of ZIP package. Use value "true" or "false". If enabled, attribute "append" cannot be "false". |
No, default is "false". |
The create new job operation can be used to execute/run a new integration job. The request may be done context-less or in context of one or more objects; this all depends on how you have configured your REST job regarding IdLocator.
<Rest>
...
<NewJob jobcfg="TheJobCfgName.xml" />
</Rest>
When using this operation, you will see a minimum of two log entries in the Admin UI. One is for the actual REST job itself and the other is for the job(s) that you execute. |
A request should be done with the "POST" method. Example:
curl -X POST http://server:8181/enovia/jaxrs/service/new-job-from-rest/Part/EV-000001/A
The following attributes can be used on the <NewJob>
element
Attribute | Description | Required |
---|---|---|
|
Defines the Job configuration name to be used |
True |
|
This flag defines if the REST job should wait for the job to complete. Default is TRUE, e.g. do not wait for completion. Note that if your configuration resolves to multiple context objects, the job will be executed asyncronously anyway. |
No |
|
This flag can be used to specify that you want to return the generated payload from the job execution. Setting this to true, requires you to run the job synchronously.
E.g. the |
No |
HTTP status codes are used to communicate the status of the call to the client.
In case an error occurs a status code other than 200 is returned along with a description of the problem.
Code | Description |
---|---|
200 |
All ok |
400 |
One of the following:
|
415 |
Unsupported media type. The service is unable to produce content on the media type requested by the client. |
404 |
No object found. The provided PathParamters/QueryParamters didn’t match any object in ENOVIA. |
500 |
Unexpected error. View the response for details. |
501 |
Unsupported operation. The requested operation is not supported. |