Adding some notes about usage

README.md

@@ -9,33 +9,59 @@ values based on the type of API called.
 It defines a set of configuration values that can be used to identify the ServiceNow instance
 information and configure the API requests.
 
-# Plugin Usage
-
-## All Steps
-
-### Required Parameters
+## Jenkins-ServiceNow Change Workflow
+
+The central idea for this plugin is to allow the deployment 
+process through Jenkins to manageeverything about a service 
+now change. One of the first 
+pieces from ServiceNow this plugin uses is the idea of a 
+standard change producer. This allows teams to build change 
+requests templates that their application uses when it is 
+deployed.
+
+Once these templates are created, the goal is to allow Jenkins 
+to carry out everything necessary for the change request, 
+from creation and data gathering (test results, commit messages, 
+and approvals), to managing the change tasks within the change 
+itself, all the way to closing the change request once it 
+completes. This is implemented using the Step mechanism that 
+is available to the Jenkins pipeline.
+
+A standard change workflow can vary based on the ServiceNow
+implementation at your company. In general, there are pre-tasks,
+implementation tasks, and post-tasks, as well as change metadata.
+This plugin provides interfaces to interact with these tasks,
+update change metadata, proceed task workflows, and attach
+information from the build to proper locations within the
+context of a change request. 
+
+## Plugin Usage
+
+### All Steps
+
+#### Required Parameters
 
 Every step must provide these two arguments in order to connect to the ServiceNow instance
 
 * `serviceNowConfiguration`
   * `instance` - Instance of service-now to connect to (https://<instance>.service-now.com)
 * `credentialsId` - Jenkins credentials for Username with Password credentials or Vault Role Credentials, if including `vaultConfiguration` below
 
-### Optional Parameters
+#### Optional Parameters
 
 `vaultConfiguration`
 * `url` - Vault url
 * `path` - Vault path to get authentication values
 
-## `serviceNow_createChange`
+### `serviceNow_createChange`
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowConfiguration`
 * `producerId` - Producer ID of the standard change to create
 
 
-### Response
+#### Response
 
 `result`
 * `sys_id`
@@ -46,7 +72,7 @@ Every step must provide these two arguments in order to connect to the ServiceNo
 * `table`
 * `redirect_to`
 
-### Example
+#### Example
 Create a service-now change and capture the sys_id and change number
 ```groovy
 def response = serviceNow_createChange serviceNowConfiguration: [instance: 'exampledev', producerId: 'ls98y3khifs8oih3kjshihksjd'], credentialsId: 'jenkins-vault', vaultConfiguration: [url: 'https://vault.example.com:8200', path: 'secret/for/service_now/']
@@ -56,20 +82,20 @@ def sysId = createResponse.result.sys_id
 def changeNumber = createResponse.result.number
 ```
 
-## `serviceNow_UpdateChange`
+### `serviceNow_UpdateChange`
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowItem`
 * `table` - Table of the item to be updated (ex. change_request, change_task)
 * `sysId` - SysId of the item to be updated
 * `body` - Json message (as String) of the properties and values to be updated
 
-### Response
+#### Response
 
 `result`
 
-### Example
+#### Example
 Update a service-now change with a short description and description
 ```groovy
 def messageJson = new JSONObject()
@@ -81,81 +107,81 @@ def response = serviceNow_UpdateChangeItem serviceNowConfiguration: [instance: '
 
 ```
 
-## `serviceNow_getChangeState`
+### `serviceNow_getChangeState`
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowItem`
 * `sysId` - SysId of the change request
 
-### Response
+#### Response
 
 `state` - String representation of the state (@see [ServiceNowStates](src/main/java/org/jenkinsci/plugins/servicenow/util/ServiceNowStates.java))
 
-### Example
+#### Example
 Get the current state of a service-now change
 ```groovy
 def response = serviceNow_UpdateChangeItem serviceNowConfiguration: [instance: 'exampledev'], credentialsId: 'jenkins-vault', serviceNowItem: [sysId: 'adg98y29thukwfd97ihu23'], vaultConfiguration: [url: 'https://vault.example.com:8200', path: 'secret/for/service_now/']
 echo response //NEW
 ```
 
-## `serviceNow_getCTask`
+### `serviceNow_getCTask`
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowItem`
 * `sysId` - SysId change to get CTask from
 * `ctask` - String representation of CTask (see [ServiceNowCTasks](src/main/java/org/jenkinsci/plugins/servicenow/util/ServiceNowCTasks.java))
 
-### Response
+#### Response
 
 `result` - an array of results
 * `sys_id`
 * `number`
 * `short_description`
 
-### Example
+#### Example
 Get ctask of a service-now change
 ```groovy
 def response = serviceNow_getCTask serviceNowConfiguration: [instance: 'exampledev'], credentialsId: 'jenkins-vault', serviceNowItem: [sysId: 'agsdh0wehosid9723h30h', ctask: 'UAT_TESTING'], vaultConfiguration: [url: 'https://vault.example.com:8200', path: 'secret/for/service_now/']
 def ctaskSysId = createResponse.result[0].sys_id
 def ctaskNumber = createResponse.result[0].number
 ```
 
-## `serviceNow_attachFile`
+### `serviceNow_attachFile`
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowItem`
 * `sysId` - SysId to attach to (can be Change Request or CTask)
 * `body` - String body of file to attach
 
-### Response
+#### Response
 
 `result`
 
-### Example
+#### Example
 Attach file to item in service-now
 ```groovy
 def myFile = readFile file: 'my-test-file.txt'
 serviceNow_attachFile serviceNowConfiguration: [instance: 'exampledev'], credentialsId: 'jenkins-vault', serviceNowItem: [sysId: 'agsdh0wehosid9723h30h', body: myFile], vaultConfiguration: [url: 'https://vault.example.com:8200', path: 'secret/for/service_now/']
 ```
 
-## `serviceNow_attachZip`
+### `serviceNow_attachZip`
 
 Attach a zip file (from the current directory) to a service-now item
 
-### Required Parameters
+#### Required Parameters
 
 `serviceNowItem`
 * `sysId` - SysId to attach to (can be Change Request or CTask)
 * `filename` - Filename of the zip file to attach
 
-### Response
+#### Response
 
 `result`
 
-### Example
+#### Example
 Attach zip to item in service-now
 ```groovy
 zip zipFile: 'my-zip-file.zip', glob: '*.txt'