Service Management as a Source

This chapter describes the use case where an already established service management system (ticket system) at the customer site is used as input for identity management relevant actions. Examples are creation and modify requests for users or privileges or requests for privilege assignment.

Detailed Definition

This use case assumes that the customer has already a comprehensive ticketing or service management system in place that is used for all kinds of requests as there are for example:

  • Orders for new hardware

  • Orders for new software or software upgrades

  • Requests for any type of material to be ordered, for example office utilities, printer cartridges.

  • Requests for access to specific resources for example file shares or special functionality in software systems (for example Active Directory, SAP).

Especially the last type is subject to be managed fully automatically by an identity management system. This can help automating the provisioning process and is also important for complete auditing in that area.

Because the employees of the company are used to this ticketing system and its user interface it might be difficult to replace it with a new user interface of the identity management system. Thus a better approach is to connect the ticketing system with DirX Identity.

The next figure shows the scenario in more detail:

Scenario ITSM as source

This scenario assumes that the ticketing system (Service Management as a Source) is integrated via a web service interface:

  • A user creates a ticket in the service management system.

  • The system detects that this is a topic that can be sent to the Identity Management system. It generates a web service request (the Ticket Request) and sends it to the corresponding Web Service.

  • The Web Service processes the ticket and converts it into DirX Identity’s internal order format and starts the relevant Ticket Request Workflow if necessary.

  • Next it sends a Ticket Response with the result (ticket processing ok or not ok) to the calling client. The ticket request operation is complete.

  • In DirX Identity the Ticket Request Workflow is processed. This is completely configurable by the customer. The workflow can start sub workflows (typically Approval Workflows for assignment approval) and can indicate provisioning requests that result in Provisioning Workflow activities.

  • The Ticket Request Workflow can be configured to watch the completion of the sub workflows as well as the completion of all provisioning requests (activity Done?).

  • After completion a Send Response activity could actively send a response to the calling client but normally the client is not prepared receiving not requested responses. Instead of that the Service Management system sends status requests either from time to time to check the open tickets or if the user wants to know the ticket status.

As stated above, the described scenario assumes that a web service interface is used between the Service Management system and DirX Identity. The DirX Identity DVD comes with a sample of such an interface that can be used to interface a specific Service Management system in a customer environment. Read the follow-on tutorial "Working With Source Tickets" in the DirX Identity Tutorial to perform the example use case in the sample domain to understand the feature.

Of course there are other interface technologies that could be used:

  • File-based interfaces in various formats (CSV, LDIF etc.)

  • JMS-based interfaces

  • A pure Java interface

We recommend using a web service interface.

Evaluation of this Use Case

This section elaborates on advantages and disadvantages of this solution.

Advantages

  • User interface for end users does not change.

  • End users have the same interface for all requests in the company.

  • Processes in the company stay almost the same.

Disadvantages

  • Integration between the ticketing system and DirX Identity requires considerable effort.

Additional Documentation

Besides the information in this document you can find additional documentation in the DirX Identity documentation:

  • Read the follow-on tutorial "Working With Source Tickets" in the DirX Identity Tutorial. Perform the example use case in the sample domain to understand the feature.

  • Read the description of the "Process Ticket Workflow" workflow in the DirX Identity Application Development Guide.

  • Find JavaDoc for our sample source ticket application on the DVD in the folder:
    Documentation → DirXIdentity → ServiceMM → SampleSourceTicketApplication.

Set Up and Configuration

Perform these tasks:

  • Implement an interface between the ticketing system and DirX Identity. Use the sample interface delivered with DirX Identity on the DVD.

  • Configure one or more corresponding Process Ticket workflows in the Provisioning view that handle ticket requests.

  • Test the solution thoroughly.

These parts must fit together to work correctly.

Implementing the Interface

Before we explain how to implement the interface, we explain the sample interface that comes with DirX Identity.

Understanding the Sample Interface

The sample web service interface architecture delivered with DirX Identity in the folder Additions → WorkingWithSourceTickets is shown in the next figure:

Sample Interface Architecture

It comprises these parts:

  • DirX Identity provides Request Workflow Web Service that allow starting and controlling request workflows. This is an official interface of DirX Identity described by a WSDL. For more information see the chapter "Workflow Management Web Services" in the DirX Identity Integration Framework Guide.

  • The Sample Web Service shows how a custom web service interface could work. It can run either as standalone application or inside Tomcat. The Sample Web Service demonstrates how a custom web service could behave. It has its own WSDL. It is a slightly enhanced SPML format. It consists of:

  • The Request Workflow Client interface that uses the Request Workflow Web Service.

  • The client gets orders from the Ticket Converting module. This component builds orders from the incoming tickets and vice versa. The order format must comply with the format that is required by DirX Identity.

To allow easy generation and modification of various ticket formats, a Sample Ticket Interface is provided. It reads requests from files, passes them to the Sample Web Service and returns responses.

The sample web service delivery comprises these parts:

  • A lib folder that contains the sample web service and the sample client.

  • The Sample Web Service that was derived from SPML and is located between the service management system and DirX Identity. The web service can be started in two ways:

  • A start script for standalone application: runServer.bat (Windows only).

  • A sourceTicketing.war file that enables to deploy and run the web service in Tomcat.

  • A start script to run the Sample Web Service Client: ticketClient.bat (Windows only). This client simulates a customer service management system that sends tickets to the sample web service and receives the corresponding responses.

  • A script that executes the client with a specific sample ticket: CreateUserWithRoles.bat processes the ticket sampleTickets/CreateUserWithRoles.xml. See the DirX Identity Tutorial’s section 'Working with source tickets' for a detailed description of this use case.

  • Another script CheckStatus.bat executes the sampleTickets/CheckStatus.xml ticket to evaluate the status of the previous request.

  • Find more sample tickets in the folder sampleTickets. The tickets work in the My-Company sample domain and comprise:

  • Creation tickets for users (createUser.xml), roles (createRole.xml), permissions (createPermission.xml) and groups (createGroup.xml).

  • Creation tickets for privilege assignments (addRoleAssignment.xml and addPermissionAssignment.xml).

  • A creation ticket for a user with assignments: createUserAddRoles.xml.

  • Modification tickets for users (modifyUser.xml) and roles (modifyRole.xml).

  • A modification ticket for a role assignment (modifyRoleAssignment.xml).

  • Deletion tickets for users (deleteUser.xml), roles (deleteRole.xml) and permissions (deletePermission.xml).

  • Deletion tickets for privilege structures (deleteRoleAssignment.xml and deletePermissionAssignment.xml).

  • A sample for a cancel requests for a role assignments (cancelAddRoleAssignment.xml).

  • A status request for a user creation request (statusCreateUser.xml).

It is easy to modify the tickets so that they are applicable for your domain but it is not very probable that the file based SPML-like XML interface is what you need for interfacing your service management system to DirX Identity.

The sample web service command line is (can be displayed with runServer.bat –help):

runServer.bat [-host host] [-port port] [-wfhost wfhost] [-wfport wfport] [-wfuser wfuser] [-wfpwd wfpwd] [-wfpath wfpath]

-host host - sample web service host name

-port port - sample web service port

-wfhost wfhost - request workflow web service host name (runs in Java-based server)

-wfport wfport - request workflow web service port

-wfuser wfuser - request workflow web service user name

-wfpwd wfpwd - request workflow web service user pwd

-wfpath wfpath - path to workflow to be used for ticket processing in Identity

Example: runServer.bat -host myIdsJHost -port 40999

The sample web service client command line is:

ticketClient.bat [-logDir logdir] [-genReqId] [-user user] [-pwd pwd] [-endpoint endpoint] [spmlRequestFile [-sleep sec] [-status reqnum] [-cancel reqnum] …​]

-logDir dir - directory to log requests and responses (no logging by default)

-genReqId - generate dynamic request ids (false by default)

-user user - user name for sample web service

-pwd pwd - password for sample web service

-endpoint endpoint - address of sample web service

spmlRequestFile - file containing the ticket request to be processed

-sleep sec - number of seconds to wait before next operation

-status reqnum -

-cancel regnum - index of data request on command line that should be canceled

regnum - index of data request on command line the status or cancel request is requested for (positive number means that the index counts from the beginning, negative number means that the index counts from the end of the command line).

Example: ticketTest.bat createUser.xml -user cn=User,cn=My-Company -sleep 3 createUser.xml -sleep 10 -status 1 addRole.xml

Implementing Your Own Interface

First you have to decide about the interface technology. As stated above we recommend using a web service based interface because this is neutral regarding programming languages and you can reuse many parts of the sample interface.

Interface Architecture

On the DVD we provide the source code for our sample web service and client in the folder:

Additions → ServiceMM → SampleSourceTicketApplication

The corresponding JavaDoc you can find on the DVD in the folder:

Documentation → DirXIdentity → ServiceMM → SampleSourceTicketApplication

As described above, you can play with the ready-to-use sample application.

Design your own interface and use parts of the delivered sample application to implement it:

  • Design your Custom WSDL.

  • Think about deployment, for example whether you want to use a base technology like Tomcat.

  • Create the Custom Web Service component (use the existing source code from the web application).

  • Change the Ticket Converting component so that it converts your ticket format to the order format of DirX Identity and vice versa. This means that you have to create a class that implements the interface TicketTransformer. Pass the converted ticket orders to the TicketProcessor instance and pickup responses. Convert responses with the TicketTransformer back to original format and return them to the client. The method SPMLRequestPortTypeImpl.processSpmlRequest() shows the core of such processing.

  • Create a Web Service Client based on your Custom WSDL and integrate it into your existing Service Management solution.

  • Test the whole solution thoroughly.

Configuring Process Ticket Workflows

Set up the necessary request workflow templates for manual provisioning:

  • In the Provisioning → Request Workflows view create a workflow folder for all request workflows that you need for ticket processing (for example Ticket Processing).

  • Copy the workflow template Service Management → Process Ticket from the Default tree.

  • Rename the copied workflow to reflect its use. Name it according to the source ticketing system from where it is used.

  • Adapt the workflow configuration as required.

Ticket Configuration

This chapter discusses various aspects of the ticket content. The ticket must comprise all information that is important for DirX Identity to process the ticket correctly as there are:

  • A ticket identifier. This identifier is important if you want to abort the ticket later on or if you need to request the ticket status. In our sample tickets this is the requestID attribute.

  • Alternatively you could use the correlation ID that is passed to the calling application in the ticket response. In our sample tickets this is the correlationID attribute of a ticket response.

  • Of course the ticket requires an identifier for the object that shall be processed. Typically you will use a DN to define additionally the path in the Identity Store. If it is not possible to provide a path within the ticket, you need to perform some calculation in the web service.

  • The ticket defines also all attributes of the object as well as links to other objects.

  • It is good practice to provide the ticket request workflow that shall be used to process the ticket according to its type. Ticket types and the setup ticket request workflows must fit together.

Running the Use Case

Create samples of all ticket types in your source ticket system that you want to process. Test all intended use cases thoroughly. Typical use cases are:

  • Create an object (user, role, permission, group). Optionally a user creation request can contain privilege assignments.

  • Modify an object (user, role, permission, group). Optionally a user modification request can modify privilege assignments.

  • Delete an object (user, role, permission, group).

  • Status requests for all types of requests.

Alternative or Extended Configurations

The default workflows coming with DirX Identity show only specific use cases. Here are some examples of possible modifications.

Building Separate Request Workflows

The default sample ticket processing workflow handles additions, modifications and deletions. If you want separate processing for different types of tickets, create multiple request workflow definitions and then calculate the request workflow DN in your web service.

The workflow that will be used to process tickets for the provided samples is evaluated in the following steps:

  1. Check whether the operational attribute workflowPath of the SPML request is present. For an example see the createUserWithRoles.xml sample ticket. This enables to specify a workflow for each individual request at the client side.

  2. Check whether the command line parameter –wfpath path of the SPML web service server is set (runServer.bat).

  3. If nothing is configured, the Request Workflow Client module uses per default the Definitions/My-Company/Service Management/Process Ticket path.

You can also create request workflow definitions for example for different object types or according to other criteria and then calculate the correct request workflow definition to start in your web service corresponding to the created ticket.

Using a File-based Interface

Instead of using a web service, you can use a file-based interface. You source ticket system creates tickets in some format in files and puts it to a request transfer file folder.

You have to implement a service that regularly checks for incoming files (tickets), processes it and passes it over to DirX Identity where it starts the corresponding request workflow definition. If the start was ok, delete or move the original ticket file.

After the ticket is processed, write a response to a response transfer file folder where the source ticket system can look up these results from time to time or on request.

As you can see there are many ways to build interfaces between a source ticket system and DirX Identity. At the end there is always a conversion of the ticket into DirX Identity’s order format and the start of the ticket processing workflow.