Workflow Management Web Services

DirX Identity provides Web services for managing request workflow instances. They allow clients to create a workflow instance, read, change, suspend and resume it.

The workflow services are automatically deployed to the embedded Tomcat Web container of each IdS-J server. They cannot be deployed to another, standalone Web container! The Web Service interface is provided as a Web Service Description Language (WSDL) file together with a number of imported XML schemata in the following folder of each IdS-J server of the DirX Identity installation:

install_path/ids-j-domain-Sn/extensions/com.siemens.idm.requestworkflow/webapps/workflowService/WEB-INF\wsdl.

This chapter describes the workflow operations and some other topics, like authentication and authorization.

Operations

The next sections describe the Workflow Management Web Services operations, including:

  • listDefinitions - read the workflow definitions matching filter criteria.

  • createInstance - create and start a new workflow.

  • getInstance - read the current state of a workflow instance.

  • listInstances - read the current state of workflow instances matching filter criteria.

  • getWorklist - read the workflow activities where the user is a participant.

  • modifyInstance - modify a workflow instance or its activities.

  • suspend - suspend a workflow .

  • resume - re-start a workflow.

  • abort - cancel a workflow or activity.

  • activate - activate an activity.

  • verify - starts a verification workflow and returns its error messages - if any.

  • waitForIdle - wait until the workflow is idle - finished or in a people activity.

  • notifyParticipantChanged - notify that a participant in a workflow has been changed.

  • updateCertification - update the provided resource orders in a delta mode.

  • bulkApproval - accept or reject a couple of approval tasks in one chunk.

Each operation accepts a request element and returns a response element. For more details see the specific chapters.

On a failure, each request will return a fault response. In addition to the attribute requestID taken from the request, it contains the following attributes or elements:

  • requestType - the request name.

  • error - an error string taken from an enumeration that categorizes the error type.

  • errorMessage - an error message that typically contains the appropriate error log.

List Definitions

Clients can use listDefinitions operation to obtain a number of workflow definitions matching the passed-in filter criteria.

The service accepts the common attributes language, requestID and domain (see the section on Common Parameters).

In addition to the common element returnData (see the section on Common Parameters), the service accepts an optional element definitionFilter of type DefinitionFilterType. This type contains a number of optional elements that are compared with the corresponding attributes of the workflow definitions:

  • operation, subjectType, resourceType and initiator are simple String elements simply compared with the corresponding workflow definitions LDAP attributes.

  • nameFilter - allows you to specify the matching conditions for the workflow definition name, which can be:

    • the DN of the workflow definition,

    • its path - an inverse DN notation without the leading workflow definition base (e.g. Definitions/My-Company/…​)

    • or a number of value assertions with a match operation (equals, startsWith, endsWith, contains).

  • definition - allows you to pass criteria to specify the workflow definition from where to create the instance.

    • If the client provides the DN of the workflow definition LDAP entry in the nameFilter/dn element, the service instantiates this one without checking any other criteria. If no DN is given, the service takes the path of the workflow, an inverse DN notation without the leading workflow definition base (e.g. Definitions/My-Company/…​). In the other cases, the service tries to find the best suitable definition by matching the other input parameters (operation, initiator, subject, resource) with the "When Applicable" criteria of the workflow definitions.

The following optional elements are matched with the "When Applicable" criteria of the workflow definitions:

  • initiator - the DN of the initiating user.

  • subject - the order that holds one or more attributes of the workflow subject.

  • resources - the order that holds one or more attributes of a workflow resource. Typically, a resource represents a user-privilege assignment.

The response contains the attribute requestID and a list of matching elements workflowDefinition with the following elements:

  • name - the name of the workflow definition.

  • id - the identifier; that is, the DN of the workflow definition.

  • requestWorkflowType - the type of the request workflow.

  • description - a description of the workflow with message placeholders resolved by their nationalized text fragments.

Create Instance

With the operation createInstance, a client can create and start a workflow. The operation requires a createInstanceRequest as input and returns a createInstanceResponse. If the DN of a workflow definition is provided, this one is instantiated and filled with the other parameters: subject, resource, initiator, context. Else the input parameters (operation, subjectType, resourceType, initiator, subject, resource) are used to find the best suitable definition (see listDefinitions) and this is instantiated.

The request accepts the following optional (XML) attributes:

  • waitForTermination - if true, returns when workflow is finished or timeout reached. Default is false.

  • waitForIdle - if true, returns when workflow is idle (either finished or in a people activity) or timeout reached. Default is false.

  • timeout - the maximum time in milliseconds until the workflow service is waiting for the workflow to be finished or idle.

  • causeRefID - the reference ID in audit trails denoting the ID of the causing audit trail.

For the common attributes language, requestID and domain, see the section on Common Parameters.

The request accepts the following optional elements:

  • correlationID - a parameter that is stored in the workflow context and may be used from a client to identify the workflow started upon a request. Currently, it is used by the ticket service and contains the request ID produced by the client.

  • definition - allows you to pass criteria to specify the workflow definition from where to create the instance.

    • If the client provides the DN of the workflow definition LDAP entry in the nameFilter/dn element, the service instantiates this one without checking any other criteria. If no DN is given, the service takes the path of the workflow, an inverse DN notation without the leading workflow definition base (e.g. Definitions/My-Company/…​). In the other cases, the service tries to find the best suitable definition by matching the other input parameters (operation, initiator, subject, resource) with the "When Applicable" criteria of the workflow definitions.

  • initiator - the DN of the initiating user. If it is missing, the service assumes the authenticated user as the initiator. The access policies for executing a workflow are applied to this user.

  • subject - an order considered the subject of the workflow. It is one of addOrder (subject is to be created), modifyOrder (subject is to be changed), deleteOrder (subject is to be deleted) and infoOrder (when a resource is to be assigned to that subject).

  • resources - none, one or many resource orders. Currently, these are user-privilege assignments and can be one of addOrder (assignment to be created), modifyOrder (assignment to be changed) or deleteOrder (assignment to be revoked).

  • context - a list of String attributes that go into the context of the created workflow. Note that activity context attributes are not evaluated in the create Instance request, but in modify and list Instances requests!

For the common elements like returnData, see the section on Common Parameters.

The response contains the attribute requestID and the following elements:

  • workflowID - the workflow ID, which can be used in other operations, especially in modifyInstance to identify the workflow instance.

  • workflowPath - the path of the workflow instance, i.e. the inverse DN notation without the workflow instance base; for example, My-Company/Approval/4-Eye-Approval/etc.

  • workflowInstance - the representation of the workflow instance is only returned, if returnData was set to 'everything'. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations including their states. See the definition of the WorkflowInstanceType in the XML schema.

Get Instance

With the operation getInstance, a client can read a workflow instance.

In addition to the common attributes language, requestID and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID with the identifier of the workflow. It is returned in the response of operations that return one or more workflow instances; for example, createWorkflow or listInstances.

The response contains the attribute requestID and one of the following elements:

  • workflowID - the workflow ID, which can be used in other operations, especially in modifyInstance to identify the workflow instance.

  • workflowInstance - if returnData was set to 'everything', the complete workflow instance is returned in this element. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations including their states. If returnData was set to "matchingActivities" only the activities matching the activity filter criteria are returned. See the definition of the WorkflowInstanceType in the XML schema.

List Instances

With the operation listInstances a client can obtain a number of workflow instances matching the passed-in filter criteria.

The service accepts the common attributes language, requestID and domain (see the section on Common Parameters).

In addition to the common element returnData (see the section on Common Parameters) the service accepts the optional elements workflowInstanceFilter of type WorkflowAndActivityFilterType and resultConstraints of type ResultConstraintsType.

The WorkflowAndActivityFilterType type extends a WorkflowInstanceFilterType and contains the optional element workflowActivityFilter of type ActivityInstanceFilterType.

The WorkflowInstanceFilterType contains the following optional elements:

  • correlationID - the string to be used by clients (e.g. ticket issuing systems) to correlate workflow instances to internal ID’s.

  • operation - the operation String (create, modify, etc) that is taken from the associated workflow definition.

  • definitionFilter - an element of type NameFilterType, which contains one of the elements name, path or dn, which refer to the corresponding attributes of the workflow definition.

  • initiator - the DN of the user who created the workflow.

  • subjectType - the object description name of the workflow subject; for example, dxrUser.

  • subjectID - the DN of the workflow subject.

  • resourceID - the DN of a workflow resource.

  • resourceType - the object description name of the workflow resource.

  • requestWorkflowType - the type of workflow.

  • state - the state of workflow.

  • started - an element of type TimestampFilterType that allows you to search for workflows, which were started after, before or exactly at a certain point in time. The time is denoted in Z-format; for example, "20100701000000Z".

  • expires - an element of type TimestampFilterType that allows you to search for workflows, which expire after, before or exactly at a certain point in time. The time is denoted in Z-format; for example, "20100701000000Z".

  • error - an element of type MultiValueAssertionType, which allows you to specify match criteria for error messages. You can pass a number of <valueAssertion> elements each containing an element <value> and an attribute "matchOperation" with one of the values "equals", "startsWith", "endsWith" or "contains".

  • owner - the DN of the owner of the workflow definition.

  • expertFilter - an element of type ExpertFilterType, where you can pass a LDAP filter string in the element <filter>.

The ActivityInstanceFilterType contains the following optional elements -

  • nameFilter - an element of type MultiValueAssertionType, which allows you to specify match criteria for the name of an activity. You can pass a number of <valueAssertion> elements each containing an element <value> and an attribute "matchOperation" with one of the values "equals", "startsWith", "endsWith" or "contains".

  • title - an element of type MultiValueAssertionType, which allows you to specify match criteria for the activity title. You can pass a number of <valueAssertion> elements each containing an element <value> and an attribute "matchOperation" with one of the values "equals", "startsWith", "endsWith" or "contains".

  • type - the string compared with the attribute dxmType of an activity.

  • activityType - the string compared with the attribute dxmActivityType of an activity.

  • activitySubType - a specific attribute that indicates the type of a people activity.

  • dueDateEnabled - a Boolean flag that indicates the existence of a due date for the order.

  • description - an element of type MultiValueAssertionType, which allows you to specify match criteria for the attribute description of an activity. You can pass a number of <valueAssertion> elements each containing an element <value> and an attribute "matchOperation" with one of the values "equals", "startsWith", "endsWith" or "contains".

  • state - the state of an activity.

  • applicationState - the application state of an activity.

  • participant - the DN of a participant of the activity.

  • category - the category of an activity.

  • started - an element of type TimestampFilterType that allows you to search for activities, which were started after, before or exactly at a certain point in time. The time is denoted in Z-format; for example, "20100701000000Z".

  • expires - an element of type TimestampFilterType that allows you to search for activities, which expire after, before or exactly at a certain point in time. The time is denoted in Z-format; for example, "20100701000000Z".

  • ended - an element of type TimestampFilterType that allows you to search for activities, which finished after, before or exactly at a certain point in time. The time is denoted in Z-format; for example, "20100701000000Z".

  • escalationLevel - an integer denoting the escalation level of an activity.

  • retryCount - an integer denoting the retry count of an activity.

  • retryLimit - an integer denoting the configured retry limit of an activity.

  • lastRetryTime - the timestamp when the activity was last restarted after a timeout.

  • waitBeforeRetry - an integer denoting the configured waiting time before it is re-started after a temporary error.

  • signApprove - the activity definition option requesting signature in case of an accepted approval.

  • signDeny - the activity definition option requesting signature in case an approval is rejected.

  • contentReadOnly - the activity definition option prohibiting changes in an approval activity.

  • approvalResult - the result of an approval activity (ACCEPTED or REJECTED), taken from the application state. Note that this attribute is only set at that activity instance, where the decision was taken. Other depending activities may inherit the application state, but not the approval result. This allows you to decide, which approver has taken the decision.

  • reason - an element of type MultiValueAssertionType, which allows you to specify match criteria for the reason given with an approval. You can pass a number of <valueAssertion> elements each containing an element <value> and an attribute "matchOperation" with one of the values "equals", "startsWith", "endsWith" or "contains".

  • expertFilter - an element of type ExpertFilterType, where you can pass a LDAP filter string in the element <filter>. Note that multi-value assertion types are OR-based; that is, the multi assertion is fulfilled when at least one contained assertion value is fulfilled.

The ResultConstraintsType contains the following optional elements:

  • applyTo - an element of type ResultConstraintsApplyToEnum. Defines the entry types to which the result constraints apply: workflows level or activities level.

  • range - an element of type RangeType that contains two elements: itemFrom and itemTo. Note that the itemFrom element is deprecated and should not be used. The element itemTo has a default value of 100 and defines the size limit (number of the returned results).

  • sortCriteria - an element of type SortCriteriaType; used to generate the sort criteria that will be applied on the returned entries.

The response contains the attribute requestID and a number of either one of the following elements:

  • workflowID - the workflow ID, which can be used in other operations, especially in modifyInstance to identify the workflow instance.

  • workflowInstance - each matching workflow instance is returned in such an element,but only if returnData was set to everything. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations including their states. If returnData was set to matchingActivities, only the activities matching the activity filter criteria are returned. See the definition of the WorkflowInstanceType in the XML schema.

Get Worklist

With the operation getWorklist, a client can obtain the workflows where he is a participant of an activity.

The service accepts the common attributes language, requestID and domain (see the section on Common Parameters).

The client typically doesn’t need to supply any parameters. The service returns all workflows where the authenticated user is a participant. More exactly, each workflow contains only those activities with the user as participant.

The client can optionally supply the following elements to either reduce the number of workflows or change the participant:

  • participant - the string with the DN of a user. If this element is supplied, not the authenticated user but the given user DN is taken as participant. Only those activities are returned, where that user is a participant. The authenticated user must have the access right to read the participant’s activities.

  • workflowInstanceFilter - the criteria for narrowing the list of returned workflows and activities. This element is described in more detail in the section on list Instances.

  • resultConstraints - defines the filter and sorting criteria that will be applied on the list of returned workflows and activities. This element is described in more detail in the section "List Instances".

The response contains the attribute requestID and a list of workflowInstance elements. For more details on a workflow instance, see the section "List Instances". The response also contains the Boolean flag sizeLimitExceeded which indicates that the search returned less entries than requested; see also constraints.range.itemTo.

Modify Instance

With the operation modifyInstance, a client can change the state of a workflow instance and of its activities.

In addition to the common attributes language, requestID and domain (see the section on Common Parameters), the service accepts the following optional attributes:

  • timeout - the maximum timeout in milliseconds to wait.

  • causeRefID - the string used in audit trails as a reference to the causing audit trail.

In addition to the common element returnData (see the section on Common Parameters) the service expects the mandatory element workflow. It represents modifications for a workflow and its activities. If you want to set or replace attributes in the workflow instance, just supply the appropriate values in the corresponding elements of the workflow element. To delete a value, you need to set the corresponding "Delete" flag to true. For example, if you want to delete the attribute "description", set the element "descriptionDelete" to true.

You can set the following attributes of a workflow instance:

  • uid - the identifier of the workflow. It is used just for identification of the workflow and is not modified itself.

  • dn - the DN of the workflow instance. It is used just for identification of the workflow and is not modified itself.

  • correlationID - the identifier for correlation of the workflow to client tickets.

  • name - the common name of the workflow instance.

  • description - the workflow description.

  • state - the state of the workflow.

  • applicationState - the application state of the workflow.

  • requestWorkflowType - the type of workflow.

  • startDate - the date and time when the workflow was started. Denoted in Z-format; for example, "20100701000000Z".

  • endDate - the date and time when the workflow was finished. Denoted in Z-format; for example, "20100701000000Z".

  • expirationDate - the date and time when the workflow is considered expired. Denoted in Z-format; for example, "20100701000000Z".

  • initiator - the DN of the user who created the workflow.

  • subjectType - the object description name of the workflow subject; for example, dxrUser.

  • subjectID - the DN of the workflow subject.

  • subject - the order element representing the workflow subject.

  • resources - the list of resource order elements representing the workflow resources, typically privilege assignments.

  • context - the list of String attributes that represent the context of the workflow. Note that activity context attributes are not yet implemented!

The following attributes cannot be changed, but they are available for reading in responses:

  • operation - the operation(s) of the workflow instance; cannot be changed!

  • path - the workflow instance path in inverse LDAP notation omitting the instance base node.

The following list of boolean sub-elements of the workflow allow you to delete workflow attributes:

  • descriptionDelete, stateDelete, applicationStateDelete, startDateDelete, expirationDateDelete, endDateDelete, subjectTypeDelete, subjectIDDelete, subjectDelete, resourcesDelete, initiatorDelete, contextDelete, requestWorkflowTypeDelete.

The <workflow> element can contain a number of <activity> elements that allow you to change certain attributes of an activity. The activity attributes you can change are:

  • description - a description of the activity. Note that the original description stored in LDAP contains placeholders for nationalization that are replaced in responses. Make sure that you use such placeholders in your modified text.

  • title - the title of the activity. Note that the original title stored in LDAP contains placeholders for nationalization that are replaced in responses. Make sure that you use such placeholders in your modified text.

  • category - the category of the activity.

  • state - the workflow state.

  • applicationState - the workflow application state.

  • startDate - the time when activity was started. Denoted in Z-format; for example, "20100701000000Z"

  • expirationDate - the time when the activity is considered expired. Denoted in Z-format, e.g. "20100701000000Z".

  • endDate - the date and time when the activity was finished. Denoted in Z-format; for example, "20100701000000Z".

  • participant - the list of user DNs that are participants of the activity.

  • escalationLevel - the integer representing the current escalation level.

  • retryCount - the integer denoting how often a timeout of the activity has occurred within one escalation level.

  • retryLimit - the integer denoting the maximum number of retries after a timeout until the activity reaches the next escalation level.

  • reason - the reason for accepting or rejecting of a participant in an approval activity.

  • activityType - the type of an activity as configured in its definition; related to LDAP attribute dxmType.

  • activitySubType - the type of an activity as configured in its definition; related to LDAP attribute dxmActivityType.

  • approvalResult - the result of an approval activity (ACCEPTED or REJECTED), taken from the application state. Note that this attribute is only set at that activity instance, where the decision was taken. Other depending activities may inherit the application state, but not the approval result. This allows you to decide, which approver has taken the decision.

  • signApprove - the activity definition option requesting signature in case of an accepted approval.

  • signDeny - the activity definition option requesting signature in case an approval is rejected.

  • contentReadOnly - the activity definition option prohibiting changes in an approval activity.

The following activity attributes cannot be changed, but they are available for reading in responses:

  • name - the name of the activity.

  • dn - the DN of the activity instance.

The following list of boolean sub-elements of the activity allow you to delete activity attributes:

  • descriptionDelete, titleDelete, stateDelete, applicationStateDelete, categoryDelete, startDateDelete, expirationDateDelete, endDateDelete, participantDelete, escalationLevelDelete, retryCountDelete, retryLimitDelete, reasonDelete, activityTypeDelete, contextDelete, approvalResultDelete.

Suspend

On receipt of the suspend request the workflow service puts the workflow instance into suspended state. It can later on be resumed by the resume request.

In addition to the common attributes requestID and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID and an optional timeout:

  • workflowID - the identifier of the workflow to be suspended.

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The response contains only the optional requestID.

Resume

On receipt of the resume request, the workflow service resumes a previously suspended workflow instance. If also an activity name has been supplied, the workflow service assumes this activity to be in state "waitInError" and resets it, i.e. starts it again.

In addition to the common attributes requestID and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID and the optional attributes timeout and activityName:

  • workflowID - the identifier of the workflow to be suspended.

  • activityName - the name of an activity that is assumed to be in state "waitInError".

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The response contains only the optional requestID.

Abort

On receipt of the abort request, the workflow service cancels the workflow instance.

In addition to the common attributes requestID and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID and the optional attribute timeout:

  • workflowID - the identifier of the workflow to be aborted.

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The response contains only the optional requestID.

Activate

On receipt of the activate request, the workflow service finishes the designated activity with state SUCCEEDED, if it is running and the activation key stored in the workflow context matches the one that was supplied in the request. See also operation verify.

This operation is typically used in user registration scenarios: The first part of the registration is realized by a verification workflow, where the user enters a number of attributes, especially their email address. The workflow verifies that the user can be created. On success, the client Web application creates an activation workflow. This creates a unique activation key and sends an email to the user containing this key. At the Web application, the user supplies his activation key and the application triggers the activate operation supplying the identifier of the activation workflow. In the activation operation, the workflow service matches the activation key with the one stored in the workflow and finishes the activity with the given name. Then the activation workflow can continue and store the new user in the data store.

In addition to the common attributes requestID, language, returnData and domain (see the section on Common Parameters) the service expects the mandatory attributes workflowID, activityName and activationKey:

  • workflowID - the identifier of the workflow.

  • activityName - the name of an activity, which is expected to be in state RUNNING.

  • activationKey - the key to be compared with the activation key stored in the workflow context. If they match, the activity state is set to SUCCEEDED.

The response contains the attribute requestID and one of the following elements depending on the input parameter returnData:

  • workflowID - the workflow ID, which can be used in other operations, especially in modifyInstance to identify the workflow instance.

  • workflowInstance - if returnData was set to 'everything', the complete workflow instance is returned in this element. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations including their states. See the definition of the WorkflowInstanceType in the XML schema.

Verify

On receipt of the verify request, the workflow service starts a verification workflow, waits until the workflow finishes and returns error messages stored in the workflow context. The workflow is either identified by its name or if the name is missing an applicable workflow is found by evaluating the operation "verify" and the attributes of the given subject. See also operation activate.

This operation is typically used in user registration scenarios: The first part of the registration is realized by a verification workflow, where the user enters a number of attributes, especially their email address. The workflow verifies that the user can be created. In case of success the client Web Application creates an activation workflow. This creates a unique activation key and sends an email to the user containing this key. At the Web Application, the user supplies their activation key and the application triggers the activate operation supplying the identifier of the activation workflow. In the activation operation the workflow service matches the activation key with the one stored in the workflow and finishes the activity with the given name. Then the activation workflow can continue and store the new user in the data store.

In addition to the common attributes requestID and domain (see the section on Common Parameters) the service expects the optional attributes workflowDefinitionName and timeout:

  • workflowDefinitionName - the name of a the workflow definition to be created.

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The service evaluates the following elements:

  • initiator - the DN of the user who is considered the workflow initiator.

  • subject - an addOrder representing the attributes of the user to be created.

  • context - a list of attributes (tag/value) that are stored into the context of the created workflow.

The response contains the attribute requestID and the following element:

  • errorMessage - the error messages that the created workflow produced .

Wait for Idle

With the operation waitForIdle the workflow service waits until the workflow is in idle state. A workflow is considered in idle state, if it is finished or a people activity is running, i.e. waiting for input of a participant.

In addition to the common attributes requestID, language, returnData and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID and an optional timeout:

  • workflowID - the identifier of the workflow.

  • timeout - the maximum timeout in milliseconds to wait until the service returns even if the workflow is not in the idle state.

The response contains the attribute requestID and one of the following elements:

  • timedout - If this boolean attribute is true, the timeout was exceeded and the client cannot expect that the workflow is in the idle state.

  • workflowInstance - if returnData was set to 'everything', the complete workflow instance is returned in this element. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations including their states. See the definition of the WorkflowInstanceType in the XML schema.

Notify Participant Changed

With the notifyParticipantChanged operation, the client informs the workflow service that the participant of an activity has been changed. The workflow service assumes that the state of the activity is set to RUNNABLE and requests the workflow engine to re-start the activity. If configured accordingly, an email will be sent to the new participant.

In addition to the common attributes requestID and domain (see the section on Common Parameters) the service expects the mandatory attribute workflowID and an optional timeout:

  • workflowID - the identifier of the workflow.

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The response contains the attribute requestID and one of the following elements:

  • timedout - if this boolean attribute is true, the timeout was exceeded and the client cannot expect that the workflow is in the idle state.

  • workflowInstance - if returnData was set to 'everything', the complete workflow instance is returned in this element. It contains the simple attributes of the instance such as uid, dn, name, state, applicationState, startDate and expirationDate and complex elements such as the subject, resources the context attributes and the activity representations, including their states. See the definition of the WorkflowInstanceType in the XML schema.

Update Certification

The updateCertification operation is a convenience operation for handling approvals in certification or attestation workflows. It allows the client to update a potentially long list of resources of an approval in several steps. Only if the client sets the submit flag to true and all resources are processed, the activity is considered finished, its state set to SUCCEEDED and its application state to ACCEPTED.

In addition to the common attributes requestID and domain (see the section on Common Parameters), the service expects the following attributes:

  • workflowID - the identifier of a the workflow instance.

  • activityName - the name of the approval activity, which is to be finished on submit = true.

  • submit - if this boolean flag is set to true, the activity is finished: its state is set to SUCCEEDED and its application state to ACCEPTED.

  • timeout - the maximum timeout in milliseconds to wait until processing of the request is finished.

The service evaluates the following elements:

  • initiator - the DN of the user who is considered the workflow initiator.

  • resource - a list of order’s considered the resources of the workflow. In case of a deleteOrder, the associated assigned is considered to be revoked.

  • context - a list of attributes (tag/value) that are stored into the context of the created workflow.

The response contains the attribute requestID and the flag complete, which indicates whether the activity is finished

Bulk Approval

The bulkApproval operation is a fast operation for handling approvals. It allows the client to approve (accept or reject) multiple workflow tasks with one request. The operation returns the response to the client immediately after the modifications in the LDAP directory are completed. This operation performs direct LDAP modifications and does not use the Identity service layer. It finishes the activity by setting the activity state to SUCCEEDED and the application state to ACCEPTED. It also removes the approver from the list of current approvers in the workflow entry, so that a subsequent request for the approver’s work list will not contain this workflow. The Web Service notifies the workflow engine and writes audit records in separate threads so they do not block returning the response.

The bulkApproval operation ignores all common attributes except the requestID.

The service expects the following attributes:

  • participantDN (optional) - the DN of the user whose tasks are approved. It is only needed, if the authenticated user approves the tasks of another person. In this case an access policy has to allow this.

  • accept - the list of requests to be approved.

  • reason (optional) - the reason for accepting a request. It is applied to all accepted requests.

  • workflowID - a list with workflow ID’s to be approved. The service approves all currently running tasks of the approver in this workflow.

  • reject - the list of requests to be rejected.

  • reason (optional) - the reason for rejecting a request. It is applied to all rejected requests.

  • workflowID - a list with workflow ID’s to be rejected. The service rejects all currently running tasks of the approver in this workflow.

  • workflowContext - not currently used by the bulkApproval service.

The response contains the attribute requestID and the failed list, which contains failed workflow ID’s. Each entry from the failed list contains:

  • id - the workflow ID.

  • name - the workflow or activity name.

  • errorCode - 1x for error at activity level, 2x for error at workflow level, 3x for error related to participant, 4x for invalid workflow ID.

  • auditRecord - for internal use only; always empty.

Implementing a Client

Using the WSDL and the XML schemata, you can generate client stubs in various technologies (for example, Java, C#, PHP).For a Java client we recommend the standard tools of the JAXWS 2 development kit.

Subject and resource orders of a request workflow follow the schema with the namespace "urn:siemens:dxm:ORDER:1:0".It is defined in the schema 'order.xsd', which in turn imports SPML 1.0, DSML 2.0, XML Signature, SAML 1.0 and some proprietary schemata (SPMLext.xsd, auditRecord-base.xsd).If you generate your client stub based on the wsdl, these schema elements are not produced, because they are only referenced via the <any> syntax: <any namespace="urn:siemens:dxm:ORDER:1:0" processContents="lax"/>.Therefore, you have to apply the JAXB source generator explicitly for the XML schema order.xsd, which recursively imports the other schema files (SPML, etc) mentioned above.

If your client is developed in Java and running on a JRE >= 6, you can make use of the classes already deployed with DirX Identity: The stub classes were generated with JAXWS 2 and compiled to the file 'com.siemens.idm.workflow.services.api.jar'.The order elements were generated already in earlier versions using the Open Source toolkit Castor and are in the files dxmOrder.jar and dxmSpml.jar.

The remainder gives some sample snippets that show how to instantiate a modify request and especially how to create and read orders:

Some constant definitions needed later on:

private static final String APPROVAL_ACTIVITY = "Approval by Privilege Managers";
private static final String U_TASPATCH_NIK = "cn=Taspatch Nik,ou=Global IT,o=My-Company,cn=Users,cn=My-Company";
private static final String U_WAGNER_RETHA = "cn=Wagner Retha,ou=Global IT,o=My-Company,cn=Users,cn=My-Company";
private static final String U_ABELE_MARC = "cn=Abele Marc,ou=Finances,o=My-Company,cn=Users,cn=My-Company";

Set the user and password into the HTTP request:

Suppose you obtained the port as WorkflowPortType from the generated stub. Then get the request context from the port and set user, password and URL the following way:

BindingProvider bp = (BindingProvider) port;
Map<String, Object> reqContext = bp.getRequestContext();
reqContext.put(BindingProvider.USERNAME_PROPERTY, user);
reqContext.put(BindingProvider.PASSWORD_PROPERTY, pwd);
reqContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, endpoint);

Instantiate a modify request type:

ModifyInstanceRequestType req = new ModifyInstanceRequestType();
req.setRequestID("string identifying this request");
req.setTimeout(5000L);

Add the modification of the workflow description:

WorkflowInstanceModificationType wfMod = new WorkflowInstanceModificationType();
req.setWorkflow(wfMod);
wfMod.setUid("<uid> obtained from a getInstance response");
wfMod.setDescription("newDescription");

Add the modification of a workflow context attribute:

AttributesType attrs = new AttributesType();
AttrType t = new AttrType();
t.setName("newName");
t.setValue("newValue");
attrs.getAttr().add(t);
wfMod.setContext(attrs);

Modification of the participants of an activity:

ActivityInstanceModificationType actMod = new ActivityInstanceModificationType();
wfMod.setActivities(new ActivityInstancesModificationType());
wfMod.getActivities().getActivityInstance().add(actMod);
actMod.setName(APPROVAL_ACTIVITY);
actMod.getParticipant().add(U_ABELE_MARC);

Create an info order as subject:

OrderType infoOrder = null;
try {
OrderFactory orderFactory = new OrderFactoryImpl();
OrderRequest infoOrder = (OrderRequest) orderFactory.createInfoOrder(
   U_WAGNER_RETHA, //subject DN
   "info." + Calendar.getInstance().getTimeInMillis(), //request id
   U_TASPATCH_NIK,  // creator DN
   null, //activationDate
  "dxrUser", //directory type
  "subject Uid",  // subject's UID required for auditing
  "dxrUser", // audit object type
  null // map of identifier attributes, required for auditing
);

    infoOrder = orderTypeFromOrder(infoOrder);
wfMod.setSubject(infoOrder);
}catch (Exception e) {
//log.error("Can not create assign order");

}

This method helps to transform an order to an order type, which is needed in requests:

/**
* @param order order from workflow, subject or resource.
* @return OrderType.
*/
public static OrderType orderTypeFromOrder(Order order) {
       if (order == null)
                 return null;
        try {
                 OrderType ret = new OrderType();
                  Element subjectElem = AbstractOrderFactoryImpl.toDomElement((OrderRequest) order);
                  ret.setAny(subjectElem);
                  return ret;
        } catch (Exception e) {
                  //log.error(e.getClass().getCanonicalName() + " while converting " + order.getClass().getSimpleName() + " to OrderType: " + e.getMessage());
        } catch (NoClassDefFoundError e) {
                  //log.error(e.getClass().getCanonicalName() + " while converting " + order.getClass().getSimpleName() + " to OrderType: " + e.getMessage());
        }
        return null;
}

The following method helps transforming an OrderType to an order, which is needed in evaluating responses:

/**
 * @param orderType orderType from workflow - subject or resource, e.g. wfRsp.getSubject().
 * @return order unmarshalled from DOM in order type.
 */
public static Order orderFromOrderType(OrderType orderType) {
       if (orderType == null)
                 return null;
        Element anyElem = (Element) orderType.getAny();
        if (anyElem == null)
                  return null;
        try {
                  return new OrderFactoryImpl().create(anyElem);
        } catch (Exception e) {
                  //log.error(e.getClass().getCanonicalName() + " while converting OrderType to Order: " + e.getMessage());
                  return null;
        }
}

Authentication

The workflow services support HTTP basic authentication based on SSL/TLS protocol and SAP cookies out of the box.

The default authenticator is configured as a Tomcat valve in the file context.xml in the META-INF folder of the Web application workflowService: install_path/ids-j-domain-Sn/extensions/com.siemens.idm.requestworkflow/webapps/workflowService/META-INF/context.xml.It handles HTTP basic authentication and proprietary authentication from Web Center applications.

Other authentication form factors, such as Single Sign-On (SSO) authentication via HTTP header can be realized using the standard Tomcat filters and valves.Support of SOAP authentication can be realized in projects by adding handlers into the JAXWS stack of the Web service.They are configured in the file sun-jaxws.xml, which is located in the WEB-INF folder of the Web application.See the JAXWS documentation for more details.The workflow service reads the DN of the authenticated user from the Web Service context: context.getUserPrincipal().

Common Parameters

This section describes attributes and elements that are used in all or at least several requests.

Attributes

  • requestID - the identifier of the request; will be returned in the response.

  • domain - if provided, will be checked against the common name of the Identity domain with which the IdS-J server is associated.This attribute helps to prevent a request from being issued to the wrong domain.

  • language - used for nationalizing the response. The default is "en".

Elements

  • returnData - if supplied, controls the amount of data returned in the response. Accepted values are:

    • identifier - the response contains only the identifier of the workflow.

    • matchingActivities - the response contains only the workflow(s) and those activities that match the given activity filter.

    • everything - returns all data - workflow(s) with all activities.

    • nothing - the response doesn’t contain any data.