Вы находитесь на странице: 1из 17

Documenting Workflow to Manage Lifecycle

Documenting Workflow to Manage Lifecycle

Date : September 27th, 2011

Version : 1.0

BMC Software and the BMC Software logo are registered


trademarks or trademarks of BMC Software, Inc.

©Copyright 2007-2011, BMC Software, Inc

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 1 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Document Control

Date Author Version Change Reference


th
27 September 2011 Carl Wilson 1.0 Initial Document Creation

Version Control - If the main contents of this document change, then a major (1.0) revision of
this document will be generated. Minor adjustments will have a minor (0.1) revision applied.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 2 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Contents

Overview____________________________________________________4

1 Document Guidelines_____________________________________5
1.1 Key Concepts 5

2 Examples________________________________________________6
2.1 Example 1 – POC 6
POC Success Factors 6
POC Scenario 6
Current Customer Process 7
Proposed Solution 8
SRM Design and Configuration 10
Atrium Orchestrator Design and Configuration 11
BAO Process 11
Design Concepts 12
2.2 Example 2 – Test Cases 13
2.3 Example 3 – Workflow Documentation 14

3 Tools____________________________________________________________17

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 3 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Overview

This document should be used as a reference for producing documentation surrounding AR


System customisations. It provides guidelines for documenting system changes which will help
manage the lifecycle of the customisation through deployment (and possible retirement).

Producing documentation with the correct content will ensure a smooth transition from
development to deployment and will allow other developers to follow what was implemented
clearly and concisely showing the changes performed.

With clear documentation, deployment, upgrades, rollbacks, re-deployment, etc become much
easier to implement.

There are a number of ways a customisation can be developed, with the key being to
understanding why a customisation was built by the developer in that particular way. Quality
documentation will allow other developers, management and even the actual developer to
understand why a customisation was done in a particular way.

Future requirements may need to leverage current customisations, without clear and concise
documentation there will be a need to reverse engineer the customisation to understand what is
occurring. This may lead to inconsistencies, and without a real understanding of the original
implementation, gaps and missing/incorrect functionality may occur.

When upgrading or migrating a system, quality documentation surrounding the existing


customisations is essential to a successful deployment. Without this documentation, there is no
way of knowing if that customisation is still required and if it is now part of OOB functionality -
thereby being rendered obsolete and it can be retired/removed before the upgrade or
migration.
Informed decisions can be made by developers, project managers, stakeholders and key
personal surrounding the environment and direction from quality documentation.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 4 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

1 Document Guidelines

1.1 Key Concepts

What makes a good document? Listed below are some key concepts to producing quality
documentation with a clear understanding:

 Clear and descriptive document Title and document Name.

 Document Control and Version history, with details of what was updated.

 Table of Contents.

 Overview of document Contents and Purpose.

 Detailed Content – including:

o Diagrams
o Screenshots
o Workflow description
o Workflow detail
o Background behind customisation – stating why the customisation is required
o Pre-requisites
o Implementation steps
o Post-requisites
o Configuration data
o Test plans/scripts
o Files required - e.g. Imbed definition/data files into the documentation

 Appendix (where applicable)

 Assumptions (where applicable)

 Responsibilities – e.g. Database Administrator required, Configuration Manager


involvement, Process Owner involvement, etc

The more detail you can provide through your documentation, the easier it will be to re-visit the
customisation by either yourself or another person. There is never “too much” information
when documenting a customisation to a system.

Having a clear understanding of the implemented customisations, leads to improved lifecycle


management of workflow. There are a number of BMC and third party tools that can aid a
developer in producing quality documentation and workflow references. (See the Tools section)

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 5 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

2 Examples

2.1 Example 1 – POC

The following shows an excerpt from a Proof of Concept document.

POC Success Factors

The following major requirements for the Proof of Concept drove the configuration decisions
and scenarios for demonstration.

The Proof of Concept (POC) will be considered a success if the following criteria is satisfied.

 BMC Software demonstrates the ability to connect SRM, via an associated Service Request,
to Atrium Orchestrator to enable automated delivery of software to the end user requesting
this service.

BMC may integrate with one of the following options:

 Active Directory
 SCCM
 Web Services
 Direct API
 SQL Database Link

POC Scenario

The customer would like to move the deployment of software to the end user into Service
Request Management. Once the request is submitted, the customer would like the delivery of
this software to the end user to be automated.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 6 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

SRM The above


diagram
depicts the
proposed
interaction
AIF required
between
the SRM
Acrobat
Viso
Lotus In Design
Work Order application
Project
and the
associated
systems for
when a user
requests a
AD
new
software
application.
SCCM

Current
Customer
Process

The current
customer
process for software delivery is:
1. User raises a request which is sent to IT Support.
2. A Support Staff member manually adds the user to the correct Active Directory group.
3. SCCM provides the software, based on the Active Directory group subscription, to the
user’s terminal.

This process is based on a Support Staff member manually updating Active Directory with the
new group required for the software access.

To automate the process to the end user, it is envisaged to provide this service via SRM and
have a backend process trigger the software delivery.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 7 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Proposed Solution

SRM

SRD

AIF

Acrobat
Viso
Lotus
In Design Work Order
Project

Atrium Orchestrator

AD SCCM

The proposed method is to use BMC Atrium Orchestrator as the integration method connecting
SRM to Active Directory (AD) and SCCM applications.

Atrium Orchestrator provides adapters to communicate with Active Directory and AR System
which can be utilised to perform the automated AD Group update and the associated SCCM
software deployment.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 8 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

The following diagram illustrates the flow for the software deployment automation:

SRM generates Work


User generates
Start Order and Triggers
SRM Request
BAO Process

Atrium
Orchestrator
receives Work
Order ID

AO updates
Work Order
Status to "In AO workflow retrieves
Progress" Work Order details
SRM to and triggers Active
Atrium Directory update
Orchestrator

AO workflow
validates
software
deployment
SCCM automatically
deploys software to
user
Yes
Successful?

No

Update and Update and Open Incident


close Work close Work to investigate
Order as Order as not unsuccessful
successful successful deployment

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 9 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

SRM Design and Configuration

To achieve the ability for users to select from a table of available software titles, the use of an
Advanced Interface Form (AIF) is required. AIF’s are OOB SRM extension forms which are
specifically supplied to allow developers to design and build necessary functionality which is not
available with the standard SRD layout.
The AIF’s are displayed in place of the Standard Service Offering and can be designed to look
and feel the same as a Standard offering with the additional fields and functionality required.

SRM AIF Design

A new AIF form will be designed and built to display the necessary functionality in allowing the
end user to select or remove software from the published catalogue.

Workflow and new fields will be added to the AIF to populate the available list of software titles
and provide the functionality to add/remove before request submission.

The AIF will be configured, within a SRD, to work with a PDT that triggers a Work Order AOT as
the backend fulfilment request. Fields from the AIF will be mapped to variables on the Work
Order containing the relevant information from the user selection. The AOT will be configured
to use a Work Order Application Template to pre-populate information related to the request.

Additional workflow for the custom Notification Filter will be created to trigger the Atrium
Orchestrator integration from the Work Order.
Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 10 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

The expected order will be:

SRD > AIF > PDT > AOT > Work Order > Atrium Orchestrator

Atrium Orchestrator Design and Configuration

To achieve the integration from Atrium Orchestrator to SRM, the following configuration within
Atrium Orchestrator will be required:

1. Configuration of the Atrium Orchestrator Adapter for Microsoft Active Directory.


2. Configuration of the Atrium Orchestrator Application Adapter for Remedy AR System.
3. Configuration of the Command Line Adapter.

To achieve the automation for the software delivery/removal, the design and configuration of
workflow processes for updating Active Directory will be built. This process will be triggered
from the associated Work Order, once the Service Request has been successfully submitted.
The Atrium Orchestrator process will retrieve the details required from the relevant Work Order,
created by the Service Request, and update Active Directory with the required Software Group
subscription or removal. The Atrium Orchestrator process will update the Work Order, in turn
updating the Service Request, when the software delivery process is started and when the
process is completed.
If the Active Directory Group returns an unsuccessful result, Atrium Orchestrator will be
configured to create an associated Incident Request to investigate the failure of the software
delivery.

BAO Process

The following BAO Process was designed and built to accommodate this POC. The steps
involved are as follows:

Software Addition

1. The AR Filter passes calls BAO Process via Web Services (SOAP) call passing in Work
Order ID and ARS Adapter name.
2. BAO process queries Remedy for the Work Order Request ID and request Submitter.
3. BAO process updates Work Order Status to “In Progress”.
4. BAO process retrieves the AD Groups from the Work Order.
5. BAO process creates XML list for all associated AD Groups.
6. BAO process loops through AD Group List.
 BAO process checks if AD Group present.
AD Group Present
 If present, BAO send queries Active Directory, via command line, for full
User DN and Group DN.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 11 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

 BAO send update command to Active Directory.


Error in AD Group Addition
 Create Incident for Failed Group Addition based on error code.
 Create Work Info Entry for Work Order with Incident ID included.
 Create Incident > Work Order associations.
 Set Process Error Flag
AD Group Not Present
 Check next AD Group in list.

7. Check Process Error Flag.


Error
 Close Work Order as “Successful with Errors”.
No Error
 Create Work Info Entry informing user software is scheduled for
deployment.
 Close Work Order as “Successful”.

Design Concepts

Following are design concepts which will be addressed in the POC:

 Creation of SRM Advanced Interface Form (AIF) containing relevant fields and workflow to
allow the user to select/de-select applications.
 Creation of associated SRM SRD, PDT and AOT to support the process.
 Creation of custom Notification Filter to support the triggering of the Atrium Orchestrator
process and integration via a Web Services call to initiate the Atrium Orchestrator process.
 Design and build of the Atrium Orchestrator process workflow to support the automated
software delivery via Active Directory (AD Group subscription) and SCCM.
 Design and build of the Atrium Orchestrator process workflow to support the update and
creation of associated AR System ITSM Application requests.
 Design and build of the Atrium Orchestrator process workflow to support the retrieval of
information from the associated AR System ITSM Application request.

2.2 Example 2 – Test Cases

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 12 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

The following shows an example of User Test Cases.

Test Cases

User Test Cases

The following test cases describe situations that would normally occur during the course of
integration processing and can be performed by end users to verify integration functionality.

# Case Procedure Expectation Pass?


1 Verify email  Set up an ‘Email Parameter’  All processing skipped Y
subject record  No exception record
exceptions – o Type = Email Subject created
exact match
o Parameter = <any
word/phrase>
o Parameter Match =
Exact Match
o Status = Enabled
 Send an email to Remedy
o Subject must be the
exact word or phrase
specified in the
parameter
o Capitalization of the
Subject does not matter
2 Verify email  Set up an ‘Email Parameter’  All processing skipped Y
subject record  No exception record
exceptions – o Type = Email Subject created
begins with
o Parameter = <any
word/phrase>
o Parameter Match =
Begins With
o Status = Enabled
 Send an email to Remedy
o Subject must begin with
the word or phrase
specified in the
parameter
o Capitalization of the
Subject does not matter

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 13 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

2.3 Example 3 – Workflow Documentation

The following example shows workflow documentation.

Main Affected Form: Shared Forms:


AR System Email Messages
Object Type Object Name Qualification Action
Filter JSS:AR System Email Execution Order: If Action (1):
Messages:Get Mail
Submit WI_510 510 Push Fields:

Execute On: Push Value To:

Submit JSS:Mail_Integration
:Submit Work Info
Run If:
Push Field If:
( 'Subject' LIKE
"%INC0___________%" ) AND 1=0
( 'Message Type' = "Incoming")
AND (NOT ( 'Subject' LIKE If No Requests
"%Create%" )) Match:

Create a New
Request

If Any Requests
Match:

Take No Action

Fields:

Name: WI_Summary
Value:
LEFT($Subject$, 99)

Name: WI_Notes
Value: $Plain Text
Body$

Name: WI_Incident
ID
Value:
SUBSTRC($Subject$,
STRSTRC($Subject$,
"INC"),
STRSTRC($Subject$,
"INC") + 14)

Name: Incoming E-

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 14 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Main Affected Form: Shared Forms:


AR System Email Messages
Object Type Object Name Qualification Action
Mail Address
Value: $From$

Name: Email GUID


Value: $Unique
Identifier$

Filter JSS:AR System Email Execution Order: If Action (1):


Messages:Get Mail
Submit INC_510 510 Push Fields:

Execute On: Push Value To:

Submit JSS:Mail_Integration
:Submit Work Info
Run If:
Push Field If:
( 'Subject' LIKE
"%INC0___________%" ) AND 1=0
( 'Message Type' = "Incoming")
AND (NOT ( 'Subject' LIKE If No Requests
"%Create%" )) Match:

Create a New
Request

If Any Requests
Match:

Take No Action

Fields:

Name: WI_Summary
Value:
SUBSTRC($Subject$,
STRSTRC($Subject$,
"Create") + 7)

Name: WI_Notes
Value: $Plain Text
Body$

Name: Incoming E-
Mail Address
Value: $From$

Name: Email GUID


Value: $Unique
Identifier$

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 15 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

Main Affected Form: Shared Forms:


AR System Email Messages
Object Type Object Name Qualification Action

Name:
chk_SubmitIncident
Value: “Yes”

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 16 of 17
©Copyright 2007-2011, BMC Software, Inc
Documenting Workflow to Manage Lifecycle

3 Tools

There are a number of BMC and third party tools that can be leveraged to produce
documentation in various formats.

These include, but are not limited to:

 BMC Developer Studio - can be used to output to RTF, PDF and HTML and display graphical
representation of workflow.

 ARUtilities – Can produce documentation in HTML.

 Panacea - Documentation and graphical representation of workflow.

 Abydos - Documentation and graphical representation of workflow.

 ARSmarts – Documentation from definition files of AR System workflow and forms.

 ARInside – HTML documentation of all AR System workflow and forms.

Documenting_Workflow_To_Manage_Lifecycle_v1.0.doc
Page 17 of 17
©Copyright 2007-2011, BMC Software, Inc