Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.
Versions
  • London
  • Kingston
  • Jakarta
  • Istanbul
  • Helsinki
  • Geneva
  • Store
Close

Set up Borland Starteam integration

Set up Borland Starteam integration

This topic lists the steps for setting up Borland Starteam integration.

About this task

Attention: The following integration is not part of the supported platform. The integration may require additional customization, typically performed by an experienced administrator or consultant, prior to operating correctly.

Procedure

  1. Create the script that will be executed on the MID Server to create the change on the Starteam server.

    This script will reside on the MID Server. It takes in parameters from the command line and uses the Starteam COM SDK to create the change request. You will need to modify the Starteam server parameters in the script as well as any custom field handling. Once this is created you can test it's functionality by running it directly on the MID Server providing the necessary parameters. You should not proceed until this works locally.

    // ----------------------------------------------------------------------------
    // create_cr.js - StarTeam SDK Application to Create Change Request
    // 2008-03-01
    // Created by ServiceNow as part of the initial deployment
    // Most of this was inherited from the SDK Examples
    //
    // Input Parameters:
    // All Command line parameters should be in the form:
    // /project:"" /u_abstract:"" /number:"" /u_original_comments:"" /caller_id-name:"" /caller_id-phone:"" /caller_id-email:""
    // /u_original_assignment_group:"" /caller_id-department:"" /caller_id-company:"" /category:"" /subcategory:"" /u_topic:""
    // Values with spaces must be enclosed in quotes
    //
    // Return:
    // Returns the new Change Request ID
    //
    //
    // ----------------------------------------------------------------------------
     
     
    //define the Starteam Server parameters
    var g_strServer = "STARTEAM1"; // Server TCP/IP address
    var g_nPort = 49200; // Server port number
    var g_strUser = "USERNAME"; // Logon user name
    var g_strPassword = "PASSWORD"; // Logon password
     
    //get the name of the Starteam project from the commandline parameters
    var g_strProject = getParameter("project"); // Project name
     
    var complete=false; //track insert event completion
     
     
    // Run it
    main();
     
    // ----------------------------------------------------------------------------
    // Main program entry point.
    // ----------------------------------------------------------------------------
    function main()
    {
     
     // Connect to the StarTeam server, and log on.
     var server = getServer();
     
     // Must enable MPX to receive events.
     server.enableMPX();
     
     var project = getProject(server, g_strProject);
     if (project != null)
     {
     // Run the app.
     run(project.DefaultView);
     }
     else
     {
     WScript.Echo("No such project: \"" + g_strProject + "\".");
     }
     
     // Disconnect from the server.
     server.disconnect();
    }
     
    // ----------------------------------------------------------------------------
    // Creates a StarTeam server object, connects to the server, and logs in.
    // ----------------------------------------------------------------------------
    function getServer()
    {
     WScript.Echo("Connecting...");
     var factory = new ActiveXObject("StarTeam.StServerFactory");
     var server = factory.Create(g_strServer, g_nPort);
     // Optional; logOn() connects if necessary.
     server.connect();
     
     // Logon using specified user name and password.
     server.logOn(g_strUser, g_strPassword);
     
     return(server);
    }
     
    // ----------------------------------------------------------------------------
    // Finds the project.
    // ----------------------------------------------------------------------------
    function getProject(server, strName)
    {
     for (var ep = new Enumerator(server.Projects); !ep.atEnd(); ep.moveNext())
     {
     var project = ep.item();
     if (project.Name == strName)
     {
     return project;
     }
     }
     return null;
    }
     
     
    function run(view)
    {
     var server = view.Server;
     var strType = server.TypeNames.CHANGEREQUEST;
     var type = server.typeForName(strType);
     
     // Create a new event source for ItemEvents of type ChangeRequest.
     var source = view.newItemEventSource(type);
     
     // Attach our event handlers.
     WScript.ConnectObject(source, "on_");
     
     // Create some ChangeRequests.
     WScript.Echo("Adding CRs...");
     var factory = new ActiveXObject("StarTeam.StChangeRequestFactory");
     
     //create the change request in the root folder
     //this could be modified to store in subfolders if needed
     var folder = view.RootFolder;
     
     //initialize the change request
     var CR = factory.Create(folder);
     
     //get parameter values from command line for standard fields
     CR.Synopsis = getParameter("synopsis"); //u_abstract
     //this is where the incident number goes
     CR.ExternalReference = getParameter("ext_ref"); //number
     CR.Description = getParameter("desc"); //u_original_comments
     
     //get parameters from command line for custom fields
     //CR.put('Starteam_FieldName', getParameter("commandLineParameterName")); 
     
     
     //save the request
     CR.update();
     
     // Wait for event to be received identifying insert complete
     while (complete != true) {
     WScript.Sleep(500);
     }
     
     WScript.Echo("Done.");
    }
     
    // ----------------------------------------------------------------------------
    // Handles the Command Line Parameters
    // ----------------------------------------------------------------------------
    function getParameter(parmName) 
    {
     if (WScript.Arguments.Named.Exists(parmName)) {
     return WScript.Arguments.Named(parmName);
     }
     else {
     return '';
     }
    }
     
     
    // ----------------------------------------------------------------------------
    // Our only event-handler.
    // ----------------------------------------------------------------------------
    function on_itemAdded(event)
    {
     // Display a message, and count the events.
     var CR = event.NewItem;
     
     WScript.Echo("Created Change Request");
     WScript.Echo("ChangeRequest=" + CR.Number );
     WScript.Echo("Incident=" + getParameter("ext_ref"));
     WScript.Echo("");
     complete=true;
    }
  2. Build the UI Action to initiate the request.
    Note: Before building the UI Action, it is helpful to review basic concepts of the MID Server and ECC Queue.
    // UI Action - Starteam Change
    // Table: incident
    // Form Context Menu
    // Condition: current.u_starteam_change==''
    //
    //To trigger a new change request in Borland Starteam
    //This rule will submit an event to the ECC Queue and requires a MID Server
    //to pickup the event and process the request
    //
    //The business rule Starteam - Process Response will populate the new Starteam
    //change request number in the incident record
    //
    // 2008-04-01 ServiceNow Professional Services 
    //
     
    // run it
    createSTChange();
     
    function createSTChange() 
    {
     
     //define MID Server to handle these requests
     var midServer = 'midServerName_goes_here';
     
     //check to see if the assignment group has a ST project defined
     if (current.assignment_group.u_starteam_project == '') {
     gs.addErrorMessage('The assignment group does not have a Starteam project.');
     return;
     }
     
     //create the command to run
     //you must provide the proper file name and path to the script residing on the MID Server
     var cmd = 'cscript c:\\scripts\\create_cr.js //NoLogo ';
     cmd += ' /project:"' + current.assignment_group.u_starteam_project + '"';
     cmd += ' /synopsis:"' + current.u_abstract + '"';
     cmd += ' /ext_ref:"' + current.number + '"';
     cmd += ' /usr_rn:"' + current.caller_id.getDisplayValue() + '"';
     cmd += ' /usr_phpmp:"' + current.caller_id.phone + '"';
     cmd += ' /usr_phea:"' + current.caller_id.email + '"';
     cmd += ' /usr_phc:"' + current.caller_id.company.getDisplayValue() + '"';
     cmd += ' /usr_phd:"' + current.caller_id.department.getDisplayValue() + '"';
     cmd += ' /usr_phteam:"' + current.u_original_assignment_group.getDisplayValue() + '"';
     cmd += ' /usr_phstxt:"' + current.category + '"';
     cmd += ' /usr_phcattxt:"' + current.subcategory + '"';
     cmd += ' /usr_phttxt:"' + current.u_topic + '"';
     
     //remove line feeds and carriage returns from the description
     var desc = current.u_original_comments.toString();
     desc = GlideStringUtil.normalizeWhitespace(desc); 
     
     cmd += ' /desc:"' + desc + '"';
     
     //create a new ecc_queue record
     var queue = new GlideRecord('ecc_queue');
     queue.initialize();
     //where to process
     queue.agent = 'mid.server.' + midServer;
     queue.topic = 'Command';
     //script to execute
     queue.name = cmd;
     queue.source = 'StarteamChange:' + current.number;
     queue.queue = 'output';
     queue.state = 'ready';
     queue.insert();
     
     //Notify the user
     gs.addInfoMessage('New change request has been queued. The new request number will be added to the incident once it is complete.');
    }

    The UI Action hands off control to the MID Server, which is going to execute the command we provided. Once the execution is completed, the stdOut and stdErr from the MID Server command will be sent back to the ECC Queue.

  3. Create a business rule to handle the incoming data.
    // Business Rule - Starteam Process Response
    // Table: ecc_queue
    // When: before insert
    // Condition: current.queue=='input' && current.topic=='Command' && current.source.toString().startsWith('StarteamChange') && current.state=='ready'
    //
    //ECC Queue rule to process input responses from Starteam MID Server integration
    //
    //The UI Action, Starteam Change will generate the output queue record to
    //be sent to the MID Server to create the Starteam change request.
    //This rule will process the stdout from the creation script
    //
    // 2008-04-01 ServiceNow Professional Services 
    //
     
    // run it
    processSTResponse();
     
    function processSTResponse() 
    {
     
     //get the response payload
     var stdout = gs.getXMLText(current.payload, '//stdout');
     var stderr = gs.getXMLText(current.payload, '//stderr');
     
     
     //if there is an error notify and abort
     //this will trigger the starteam.error event which is linked to the Starteam Error email notification
     if (stderr) {
     gs.log('Starteam Process Response Error (' + current.source + '): ' + stderr + '\n' + 'See ECC Queue sequence ' + current.sequence + ' for more detail.');
     gs.eventQueue('starteam.error',current, stdout, stderr);
     //update the queue record so it is not processed again
     current.state='error';
     current.processed=gs.nowDateTime();
     return;
     }
     
     //set response search terms
     var crLabel = 'ChangeRequest=';
     var incLabel = 'Incident=';
     
     //see if we created a change request
     if (stdout.indexOf(crLabel) == -1) {
     gs.log('Starteam Process Response Error (' + current.source + '): Could not find the new change request number in the following response. \n' + stdout + '\n See ECC Queue sequence ' + current.sequence + ' for more detail.');
     gs.eventQueue('starteam.error',current, stdout, stderr);
     //update the queue record so it is not processed again
     current.state='error';
     current.processed=gs.nowDateTime();
     return;
     
     }
     
     //it's all good at this point, let's get on with it
     
     //find the change request number in the output
     var CRStart = stdout.indexOf(crLabel)+crLabel.length;
     var CREnd = stdout.indexOf('\n',CRStart);
     var crNumber = stdout.substring(CRStart,CREnd);
     
     //find the incident number in the output
     var IncStart = stdout.indexOf(incLabel)+incLabel.length;
     var IncEnd = stdout.indexOf('\n',IncStart);
     var incNumber = stdout.substring(IncStart,IncEnd);
     
     gs.log('Processing Starteam response');
     
     //get the related incident and add the Starteam number
     var inc = new GlideRecord('incident');
     inc.addQuery('number',incNumber);
     inc.query();
     if (inc.next()) {
     inc.u_starteam_change = crNumber;
     inc.update();
     gs.log('Starteam change request ' + crNumber + ' was applied to Incident ' + incNumber);
     //update the queue record so it is not processed again
     current.state='processed';
     current.processed=gs.nowDateTime();
     }
    }
  4. If there are any unexpected results from Starteam command, fire a custom event to send a notification.
  5. Create an Inbound Email Action to handle closure.

    This section will vary based on your Starteam configuration, but the concept would be to identify an email from the Starteam email address and capture the incident number from the subject and close the related incident. Here is the related section of the inbound rule.

    //handle Starteam notification
    if (email.from.toLowerCase() == 'starteam@customer.com') {
     //get the incident number from the subject
     var subject = email.subject;
     var incidentNumber = subject.toUpperCase();
     var inc = new GlideRecord('incident');
     inc.get('number',incidentNumber);
     //set to closed and copy the body content to the close notes
     inc.incident_state = 7; 
     inc.close_notes = 'Incident automatically closed since the related Starteam Change has been closed.\n' + email.body_text;
     inc.update();
     gs.log('Incident ' + inc.number + ' has been closed automatically since we received email notice from Starteam');
    }