Upgrading to State Conductor 1.0.0

The update from State Conductor 0.x.x to 1.0.0 is a major change because the code, files, and vernacular has been changed to align more fully with Amazon State Language. Here is a list of the changes that are needed in order to upgrade to 1.0.0

• Change the mlBundle to 1.0.0 in the dependencies section of the build.gradle file
• Update 0.x.x flow documents to state machine documents
• Query to run before deploying to remove old roles
• Clean up

Change the mlBundle to 1.0.0 in the dependencies section of the build.gradle file

dependencies {
  mlBundle "com.marklogic:marklogic-state-conductor:1.0.0"
}

Update 0.x.x flow documents to state machine documents

In effort to align with Amazon State Language the "flow" documents are now called "State Machine" documents. Their location has changed, in addition to their name, and some of the schema/properties. see State Machine Definition Syntax for more information.

Query to run before deploying, to remove old roles

Run this query on each environment before deploying.

'use strict';
// execute this against the security database
declareUpdate();

if (xdmp.databaseName(xdmp.database()) !== "Security") {
  fn.error(null, "Your database is not set as Security change you database to Security");
}
  
const sec = require('/MarkLogic/security.xqy');

//removes all state-conductor privileges
xdmp.privileges().toArray()
  .map((item) => {
    return { 
      name: xdmp.privilegeName(item),
      kind: xdmp.privilegeKind(item),
      id: item
    };
  })
  .filter(item => item.name.startsWith("state-conductor"))
  .forEach((item) => {
    let doc = fn.head(cts.search(cts.andQuery([cts.elementValueQuery(fn.QName("http://marklogic.com/xdmp/security","privilege-id"), item.id.toString()),cts.collectionQuery("http://marklogic.com/xdmp/privileges")])));
    item.action = doc.xpath("sec:privilege/sec:action/text()", {"sec":"http://marklogic.com/xdmp/security"}).toString();
    sec.removePrivilege(item.action, item.kind);
  });

//removes all state-conductor roles
sec.getRoleNames().toArray()
  .map(item => item.xpath('text()').toString())
  .filter(item => item.startsWith("state-conductor"))
  .forEach((item) => {
    //call it this way to not get conflicing updates
    let uri = cts.uris(null,null,cts.andQuery([cts.elementValueQuery(fn.QName("http://marklogic.com/xdmp/security","role-name"), item),cts.collectionQuery("http://marklogic.com/xdmp/roles")]))
    sec.removeRoleFromUsers(item);
    sec.removeRoleFromAmps(item);
    xdmp.documentDelete(uri);
  });

Clean up

The upgrade is designed to be non-destructive, besides the query to remove roles. This means there there is some clean up that you can choose to do.

• remove old State Conductor jobs database. There is a new database called State Conductor executions.
• remove old State Conductor flow documents. In one of the Steps above you would have created new state machine documents, since these are new documents they would not remove the old documents in the content database.

'use strict';
declareUpdate();
xdmp.directoryDelete('/state-conductor-flow/')

Errors that could happen when upgrading to 1.0.0

If you get an error like this the ones below then make sure that you have removed the roles with the (query)[(oldRoles). This has to be done on each environment.

Task :state-conductor-dhf5-example:mlDeployApp FAILED Logging HTTP response body to assist with debugging: {"errorResponse":{"statusCode":"500", "status":"Internal Server Error", "messageCode":"CMA-ERRORCONFIG", "message":"CMA-ERRORCONFIG (err:FOER0000): MANAGE-CONFLICTINGCONFIGerr:FOER00001.0-mlA conflict has been detected:MANAGE-CONFLICTINGCONFIG: (err:FOER0000) A conflict has been detected: [...]

or

Error occurred while sending POST request to /manage/v3; logging request body to assist with debugging: [...]