In large organizations building and maintaining services is not a one man job, instead it is a process that touches many people in the organization. Figure 10.1, “SOA Governance Roles” is a copy of figure 5.6 on page 95 of the SOA Governance book by Thomas Erl et al.
With this many people and roles involved, how to you manage a project like this? Especially since in a large organization you will have many of these project running simultaneously. We would have loved to implement a full project workflow based on the figure 1 process, but two things are currently standing in our way: time and real world input. Who is going to pick up the challenge?
To get you started we created a Simplied Project Lifecycle Workflow demo that implements just 3 boxes; Requirements gathering, Service Design and Service Implementation, with one role responsible for each stage, which are a Business Analyst, SOA Architect and SOA Developer. Each role can be fulfilled by more then one person. In the demo we assigned all three roles to the admin user so we don’t have to log in and out as different users all time. The demo uses the workflow shown in Figure 10.3, “Project Workflow”. Each column represents one of the phases. The first phase being Business Analysis. The hope is this demo provides you with the building blocks to create the real world implementation we talked about earlier.
Some benefits of using this workflow are:
- Helps your organization with adoption of SOA by following proven processes. It is clear who is responsible for approval.
- Provides insight in where your projects are.
- Helps your organization work together in different teams.
- Audit features allow full history tracking.
- Released artifacts are in the repository, the artifact is automatically in escrow this way, and documentation and sources are stored along side the binaries all in one place.
Some optional benefits:
It is possible to send a BPMN event at the end of the workflow (or from anywhere else), which can kick off a release workflow to automate deployment. Though one could also write a governance query looking for a service implementation artifact with classification #ImplPass. Easy integration with other systems (think bug track systems, or time management systems)
If you want to follow along with the demo you should
- Have DTGov running; see http://jboss-overlord.blogspot.com/2013/11/bleeding-edge-governance-getting-started.html.
- Install the Eclipse BPMN2 Modeler into your Eclipse IDE, or you can try the early access JBoss Developer Studio.
For a short video see: http://jboss-overlord.blogspot.com/2013/11/soa-governance-projects-and.html
This demo shows how teams can collaborate using a ProjectLifeCycle Workflow. In this example we have a simplified Project workflow with only three phases with their respective teams. Each team delivers a set of deliverables which are uploaded to the repository. Each upload triggers a review of the artifacts. The artifacts are groupedBy an ArtifactGrouping which is represented as a parent in S-RAMP.
This demo contains three submodules:
- project-requirements: a requirements doc created a Business Analyst.
- project-service-api: a service design created by a SOA-Architect.
- project-service-impl: the service implementation created by a SOA Developer.
The overlord.demo.ProjectLifeCycle.bpmn resides in the dtgov-workflow.jar in the SRAMPPackage and this should already be deployed. Also the classification ontologies should already have been installed as part of the data seeding process during install of DTGov. In the s-ramp-ui artifacts screen you can click on Classifiers to check that the Project Review Status is present.
These classifications will be applied by the Classify nodes in the workflow as the project moves through its lifecycle.
You can create and update workflows using the Eclipse BPMN Editor, which can be installed from http://download.eclipse.org/bpmn2-modeler/updates/kepler/ (1.0 or newer). The project starts with a business analyst creating a requirements document, which is then reviewed and approved. On a successful approval a SOA-Architect creates a design, followed with another review meeting and finally a SOA-Developer creates an implementation of the design. When the implementation is reviewed the Service Implementation can be released into a formal QA process. The Deployment Process of an Artifact is covered in the dtgov-switchard demo.
To get this demo working you must be running the DTGov server and the S-RAMP repository (see documentation for the DTGov and S-RAMP projects to learn how to run the S-RAMP repository).
When the Business Analyst finishes the requirement doc project-requirments/src/main/resources/requirements-doc.txt. The next step is to build and deploy the requirements archive to S-RAMP using Maven:
$ cd project-requirements $ mvn -Pdemo clean deploy
Important
Be aware that you must supply the maven build with credentials for your S-RAMP repository. This can be done by adding a section to your settings.xml file (or by providing a custom settings.xml on the mvn command line using the -s argument).
For more information see: http://maven.apache.org/settings.html
Your settings.xml file should contain two additional server entries in the servers section:
<server>
<id>local-sramp-repo</id>
<username>admin</username>
<password>PASSWORD</password>
</server>
<server>
<id>local-sramp-repo-snapshots</id>
<username>admin</username>
<password>PASSWORD</password>
</server>
That will enable the demo profile, which will configure the Maven distributionManagement to point to a local S-RAMP repository (http://localhost:8080/s-ramp-server/). Therefore you need to be running S-RAMP on port 8080 and deployed as the s-ramp-atom context.
The build should complete successfully.
At this point there should be a number of artifacts stored in the S-RAMP repository. You can verify that by deploying the "s-ramp-ui" project and then navigating to http://localhost:8080/s-ramp-ui (or the appropriate URL for you).
You should see the following artifacts in the S-RAMP repository:
- project-requirements-<version>.jar
- project-requirements-<version>.pom
- Project-org.overlord.dtgov.demos.project.<version>
The requirements-doc.txt is shipped in the requirements-<version>.jar. Note that you can use other formats if you like. You may have expected the jar and the pom, but what created the Project-org.overlord.dtgov.demos.project.<version> artifact? In the dtgov-demos-project/pom.xml you may have noticed the following section:
<distributionManagement>
<repository>
<id>local-sramp-repo</id>
<name>S-RAMP Releases Repository</name>
<url>sramp://localhost:8080/s-ramp-server/?artifactGrouping=Project-${project.groupId}.${project.version}</url>
</repository>
<snapshotRepository>
<id>local-sramp-repo-snapshots</id>
<name>S-RAMP Snapshots Repository</name>
<url>sramp://localhost:8080/s-ramp-server/?artifactGrouping=Project-${project.groupId}.${project.version}</url>
</snapshotRepository>
</distributionManagement>
This section is active when using the demo profile, and in it we specified an artifact grouping artifactGrouping=Project-${project.groupId}.${project.version}. During the upload this ArtifactGrouping artifact is created along with groupBy relationships to this parent artifacts. The dtgov.properties file defines the following :
governance.queries=/s-ramp/ext/ArtifactGrouping[xp2:matches(@name\, 'Project.*')]|overlord.demo.SimplifiedProjectLifeCycle|UpdateMetaDataUrl={governance.url}/rest/update/{name}/{value}/{uuid}
This starts a overlord.demo.SimplifiedProjectLifeCycle workflow when a ArtifactGrouping with a name that starts with Project lands in the repository. When the workflow is created you should see a new custom property on this artifact which should look like
workflowProcessId=overlord.demo.SimplifiedProjectLifeCycle_0:4_workflowParameters=UpdateMetaDataUrl=http://localhost:8080/dtgov/rest/update/{name}/{value}/{uuid}
If you where to delete this property then a new workflow will be started, and a new property will be recreated.
The upload of the requirements also triggered an AnalysisArtifactsComplete signal to the newly created workflow, to signal the workflow that the requirements docs are ready for review. This signal was triggered by upload of the project-requirements/pom.xml. Note that in this pom we have the following properties section
<properties> <signal>AnalysisArtifactsComplete</signal> </properties>
During a MavenPom upload all properties are extracted and added as custom properties, prefixed with maven.property.; so the signal property end up as maven.property.signal with value AnalysisArtifactsComplete. When DTGov discovers this signal property it looks up the accompanying workflow referenced in the Project* ApplicationGroup artifact signals this process instance. After sending the signal the name of the property changes to _maven.property.signal.sent. When the signal is caught by the workflow, it will classify the Project* ApplicationGroup artifact with the #BaInReview classification, and start a Business Analysis Review Meeting task. This task is assigned to the ba role. You can defined roles in the standalone/configuration/overlord-idp-roles.properties. These roles can be referenced in the human task definition as the groupId.
By default the standalone/configuration/overlord-idp-roles.properties looks like
admin=overlorduser,admin.sramp,dev,qa,stage,prod,ba,arch
The admin user has all roles. So when logged in as admin you can work on ALL tasks. For this example the ba, arch, and dev roles in use. More roles can be created as needed.
You can work on your tasks by navigating to http://localhost:8080/dtgov-ui#taskInbox. After you’ve reviewed the requirements documents with all stakeholders, you go here to Claim, Start and record the Pass/Fail verdict. For the Business Analysis Review Meeting task you will need the ba role. On a Fail the workflow records the fail and loops back so that a new version can be submitted. On a Pass the workflow records the pass and enters the waiting for architecture docs complete state.
The architect can now take the detailed and approved requirements:
Requirements Document --------------------- We have a pressing need for an Hello World Service. Please develop one that can print "Hello World" when invoked.
and turn them into a design. At a minimum, for this webservice an annotated interface or a WSDL should be created. Both of these can be found in the project-service-api module. Since these are ready to go, proceed with deploying them to S-RAMP using:
$ cd project-service-api $ mvn -Pdemo clean deploy
The build should complete successfully.
You should see the following newly created artifacts in the S-RAMP repository:
- project-service-api-<version>.jar
- project-service-api-<version>.pom
In this pom the signal property
<properties> <signal>ArchitectureArtifactsComplete</signal> </properties>
will cause a ArchitectureArtifactsComplete signal to be send to the project workflow signalling that the design documents are ready for review. A review meeting should be called and someone with the arch role can pick up the Design Review Meeting task in the http://localhost:8080/dtgov-ui#taskInbox.
Finally, when the SOA-Developer has finished the implementation, it can be uploaded to the repository using
$ cd project-service-impl $ mvn -Pdemo clean deploy
The build should complete successfully.
You should see the following newly created artifacts in the S-RAMP repository:
- project-service-impl-<version>.jar
- project-service-impl-<version>.pom
In this pom the signal property
<properties> <signal>ServiceImplArtifactComplete</signal> </properties>
will cause a ServiceImplArtifactComplete signal to be send to the project workflow signalling that the design documents are ready for review. A review meeting should be called and someone with the dev role can pick up the Service Implementation Review Meeting task in the http://localhost:8080/dtgov-ui#taskInbox.
This completes this demo.