starflow-jira v0.1.0
starflow-jira
Prerequisites
In order to use this plugin, your project must have starflow as a dependency.
Install
$ npm install --save-dev starflow-jira
Usage
Using a workflow:
var starflow = require('starflow');
var steps = [
{'jira.getIssue': 'FOO-123'}
];
var workflow = new starflow.Workflow(steps);
return workflow
.addPlugin(require('starflow-jira'))
.run();
In an executable:
module.exports = function (starflow) {
var getIssueFactory = require('starflow-jira')(starflow).factories.getIssue;
function MyExecutable() {
starflow.BaseExecutable.call(this, 'myPlugin.myExecutable');
}
MyExecutable.prototype = Object.create(starflow.BaseExecutable.prototype);
MyExecutable.prototype.constructor = MyExecutable;
MyExecutable.prototype.exec = function exec() {
var getIssueExecutable = this.createExecutable(getIssueFactory);
return new starflow.Task(getIssueExecutable, 'FOO-123')
.run()
.then(function () {
var issueResponse = this.storage.get('jira.getIssue/issue');
starflow.logger.log('Got the following Jira issue: ' + issueResponse);
}.bind(this));
};
return function () {
return new MyExecutable();
};
};
Executables
Thereafter is the list of all the executable classes provided by this plugin.
Important The titles indicate the name that can be used when writing the steps of a workflow.
jira.getIssue
Given an issue key (e.g. FOO-123
), gets data about this issue.
Please go to the Get issue > Responses section of the official Jira API documentation for more details.
The step accepts a second (optional) parameter:
- withOpen (default value:
false
): open a new tab in the browser for the given issue (e.g. http://jira.example.com/browse/FOO-123)
Usage:
// for a workflow
var withOpenUrl = false;
var steps = [
{'jira.getIssue': ['FOR-123', withOpenUrl]}
];
// in an executable
var getIssueFactory = require('starflow-jira')(starflow).factories.getIssue;
var getIssueExecutable = this.createExecutable(getIssueFactory);
var withOpenUrl = false;
var myTask = new starflow.Task(getIssueExecutable, ['FOR-123', withOpenUrl]);
jira.assignIssue
Given an issue key and a username, assigns the issue to that user.
Usage:
// for a workflow
var steps = [
{'jira.assignIssue': ['FOO-123', 'bob.modnar']}
];
// in an executable
var assignIssueFactory = require('starflow-jira')(starflow).factories.assignIssue;
var assignIssueExecutable = this.createExecutable(assignIssueFactory);
var myTask = new starflow.Task(assignIssueExecutable, ['FOO-123', 'bob.modnar']);
jira.getIssueStatuses
Given an issue key, get the available statuses ("transitions" in Jira context) for this issue. Please go to the Get transitions > Responses section of the official Jira API documentation for more details.
Usage:
// for a workflow
var steps = [
{'jira.getIssueStatuses': 'FOO-123'}
];
// in an executable
var getIssueStatusesFactory = require('starflow-jira')(starflow).factories.getIssueStatuses;
var getIssueStatusesExecutable = this.createExecutable(getIssueStatusesFactory);
var myTask = new starflow.Task(getIssueStatusesExecutable, 'FOO-123');
jira.changeIssueStatus
Given an issue key and a status name, change the issue status to the one provided (if the issue workflow allows it).
Usage:
// for a workflow
var steps = [
{'jira.changeIssueStatus': ['FOO-123', 'in progress']}
];
// in an executable
var changeIssueStatusFactory = require('starflow-jira')(starflow).factories.changeIssueStatus;
var changeIssueStatusExecutable = this.createExecutable(changeIssueStatusFactory);
var myTask = new starflow.Task(changeIssueStatusExecutable, ['FOO-123', 'in progress']);
Config
Some behaviors of this plugin depend on the values of config variables, here's the list of them and their effect.
- URL (no default value, mandatory) URL of the Jira service (e.g. http://jira.example.com).
- USERNAME (no default value, mandatory) Jira username.
- PASSWORD (no default value, mandatory) Jira password.
You can set these config variables from several ways:
Env variables on your machine.
Example (assuming
index.js
contains your workflow that uses the jira executables):$ starflow_jira__URL=http://jira.example.com starflow_jira__USERNAME=bob.modnar starflow_jira__PASSWORD=password node index.js
.starflowrc
file at the root of your project (but you probably shouldn't choose this option as the credentials shouldn't be so easily accessible).Example:
{ "jira": { "URL": "http://jira.example.com", "USERNAME": "bob.modnar", "PASSWORD": "password" } }
:bulb: Recommendation Store your Jira credentials as
starflow_jira__USERNAME
andstarflow_jira__PASSWORD
variables in your~/.bash_profile
or~/.zshrc
file.
Internally, Starflow uses the rc module to handle the config values.
Storage
Some of the executables of this plugin store some values in their storage.
jira.getIssue
issue Contains the issue data (id, summary, assignee...) from the Jira server.
Example:
var starflow = require('starflow'); var steps = [ {'jira.getIssue': 'FOO-123'}, {'custom.echo': '{{/jira.getIssue/issue.summary}}'} // e.g. displays "This is the issue title/summary" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-jira')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
jira.assignIssue
assignee The name of the assignee provided in the parameters.
Example:
var starflow = require('starflow'); var steps = [ {'jira.assignIssue': ['FOO-123', 'bob.modnar'}, {'custom.echo': '{{/jira.assignIssue/assignee}}'} // displays "bob.modnar" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-jira')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
jira.getIssueStatuses
statuses Contains the list of statuses ("transitions" in Jira terms) available for a given issue.
Example:
var starflow = require('starflow'); var steps = [ {'jira.getIssueStatuses': 'FOO-123'}, {'custom.echo': '{{/jira.getIssueStatuses/statuses.transitions[0].name}}'} // e.g. displays "In progress" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-jira')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
jira.changeIssueStatus
status The status name provided in the parameters.
Example:
var starflow = require('starflow'); var steps = [ {'jira.changeIssueStatus': ['FOO-123', 'To deploy']}, {'custom.echo': '{{/jira.changeIssueStatus/status}}'} // displays "To deploy" ]; var workflow = new starflow.Workflow(steps); return workflow .addPlugin(require('starflow-jira')) .addPlugin(require('starflow-custom')) // plugin that contains the 'echo' executable .run();
Note: learn more about storage paths on the Starflow documentation page.
If you want to contribute, please take the time to update this README file with the new executables/API brought by your contribution. Thank you! :heart:
8 years ago