Merge branch 'master' of https://github.com/jazz-community/rtc-workit…

…em-bulk-mover-service

README.md

@@ -10,37 +10,57 @@ It is highly recommended to then follow the instructions provided in the [Bulk M
 ## API Reference
 This section contains the API definition for this project. While we try to do our best to keep this accurate, it is always best to have a look at the code in order to make sure that everything is covered.
 
-### base path
-You'll see the term `<root>` within the following API doc a few times. It represents the root (or base) path for this service. Assuming that your CCM server is being referred to as `localhost:7443/ccm`, the `<root>` path for this service is the following:
+### Base Path
+You'll see the term `BASE` within the following API doc a few times. It represents the root (or base) path for this service. Assuming that your CCM server is being referred to as `localhost:7443/ccm`, the `BASE` path for this service is the following:
 
 > https://localhost:7443/jazz/service/com.siemens.bt.jazz.services.WorkItemBulkMover.IWorkItemBulkMoverService
 
-### get project area
-List all available project areas.
+### List Project Areas
+List all available project areas a user has access to.
+> GET `BASE`/project-areas
 
-> GET <root>/project-areas
+You can provide a black list of project areas that should not be included in the response (e.g. in case you want the current source area not to be an option for a move). To do that, append the project areas UUID as a parameter, seperate multiple items with a comma:
+> GET `BASE`/project-areas?ignore=_3Ud7oP5aEeanwOtOCiP3RQ,_3Ud7oP5aEeanwOtOCiP3RQ
 
 *Example Response:*
-```
+```javascript
 [
    {
-      "id":"[UUID _3Ud7oP5aEeanwOtOCiP3RQ]",
+      "id":"_3Ud7oP5aEeanwOtOCiP3RQ",
       "name":"SAFe Portfolio"
    },
    {
-      "id":"[UUID _sFpSwP5aEeanwOtOCiP3RQ]",
+      "id":"_sFpSwP5aEeanwOtOCiP3RQ",
       "name":"SAFe Program"
    }
 ]
 ```
 
-### Start work item move
-This will start the core Bulk Mover operation. 
+### List Work Item Types
+List all available work item types within a project area. The `project-area` parameter is required and you have to provide the display name of the project area in order to get its work item types.
+> GET `BASE`/types?project-area="SAFe Program"
+
+*Example Response:*
+```javascript
+[
+   {
+      "id":"defect",
+      "name":"Defect"
+   },
+   {
+      "id":"com.ibm.team.apt.workItemType.story",
+      "name":"Story"
+   }
+]
+```
+
+### Start or Preview a Work Item Move
+This will start the core Bulk Mover operation. You can either preview the mapping (setting `previewOnly` to `true`) or you can try to move all workitems directly. The server response will be in the same base structure as the client request. This allows a client application like the [Bulk Mover Plug-in](https://github.com/jazz-community/rtc-workitem-bulk-mover-ui) to reuse the response in the user interface and send it back again. This is especially useful when it comes to missing data that the user needs to enter.
 
-> POST /move
+> POST `BASE`/move
 
 *Request / Response* 
-```
+```javascript
 {
    // REQUEST only
    "previewOnly":false, // true if you want to preview the changes, but do not move yet. Setting to false or providing no value will move if possible
@@ -59,7 +79,7 @@ This will start the core Bulk Mover operation.
                "identifier":"/Unassigned/Infrastructure/",
                "displayName":"Infrastructure"
             },
-			...
+	    ...
          ],
          "valueMappings":[ // a list of old values and the affected work items
             {
@@ -89,8 +109,8 @@ This will start the core Bulk Mover operation.
 ```
 
 ## Limitations
-- Custom Attributes: The handling of custom attributes is limited to the features provided by IBM. For anything else than plain text, we cannot ensure proper handling of those.
-- States: State mapping is currently not possible.
+- Mapping required custom attributes only available in the target project area is currently not implemented for all attribute types. The most important and commonly used once are implemented however.
+- Older releases of RTC may not be able to activate the service, see [this](https://github.com/jazz-community/rtc-workitem-bulk-mover-service/issues/11) discussion.
 
 ## Contributing
 Please use the [Issue Tracker](https://github.com/jazz-community/rtc-workitem-bulk-mover-service/issues) of this repository to report issues or suggest enhancements.