Tom Wellige

How to make your own modifications or simply just take a look onto the implementation to get an idea of how everything works? The following explanations will refer to the VBScript version, the Lua version however is more or less identical in its structure. The entire code of this integration is located in one single file, JiraServiceIntegration.vbs. All functionality is encapsulated in a class (JiraServiceClass), which defines properties for all parameters (with some validation) as also private and public methods. To make use of the JiraServiceClass class the JiraServiceIntegration.vbs file must be included first. This is done in the "Start" block of the GSE Action or your own GSE rule. '#inlcude "JiraServiceIntegration.vbs" Afterwards the class needs to get instantiated, its properties set and the needed public method/function called. The return value of the function is either "0" (ok) or "1" (failed), so it can be used directly for the exits of a "Insert Script Code" or "Run GSE Action" block. And this is exactly what the GSE actions of this project are doing. In order to make modifications it is not simply possible to modify the InvisionPowerServices.vbs file and re-upload it again into the SwyxWare database. This is because the file is digitally signed, which is necessary to get it included with the #include statement. The easiest way to do your own modifications is to forget about the JiraServiceIntegration.vbs file all together and use just its content within a start block of a GSE rule (instead of the #include statement), but without the digital signature. You can strip the signature yourself from the code (first line and all lines from the bottom), or simply use the content of the start.vbs file from the "vbs" folder or the download package. VBScript based\vbs\start.vbs So just do all your modifications within the start.vbs file and afterwards just copy & paste the entire content of the file into the "Start" block and then use the Insert "Insert Script Code" block to instantiate the IPS class and call its functionality Dim c Set c = new JiraServiceClass with c .sBaseURL = "https://my-service.atlassian.net" .sLoginUser = "myname@gmail.com" .sLoginToken = "1234567890" .sProjectKey = "SUP" .sSummary = "My first issue via Jira REST API" .sDescription = "Hello world" .sIssueType = "Support" sReturn = .CreateIssue end with Set c = Nothing It is highly recommended to not do any code modifications directly in the Start block, but instead use a proper editor like VS Code or Notepad++. You are now free to to any modifications within the code and use it afterwards in your own GSE rules. If you want to update the JiraServiceIntegration.vbs in the end, you need to update its signature as well. This can be done with the "SignScript" tool which can be found in the Enreach Partner Net (you need a partner login). In order to get get your own .vbs file signed, make sure that the text encoding is UTF-8-BOM. This can easily be checked/configured with Notepad++. Please feel free to ask any questions regarding the code, implementation or distribution (signing, including, etc.) in the Open ECR Extensions forum. Most of the above mentioned is also true for the following extensions. So there is lots more to explore Invision Power Services (IPS) Integration (REST API usage, API Key/Token authentication) Longest Waiting (Database usage) Open Queue (Database usage) Zendesk Integration (REST API usage, API Key/Token authentication)

VBScript Lua This GSE action checks the status of an existing service issue. Example call routing scripts can be found here A.3 - Example: Check Status and here A.4 - Example Check Status and Add Comment. Configure action parameters By double clicking a parameter in the list, you can edit it. BaseURL Required This is the ase URL of your Jira Service page, for example: https://my-service.atlassian.net LoginUser Required This is the email address of the Jira user you want to authenticate with. Please refer to 1 - Preparations for more details. LoginToken Required This is the API Token of the Jira user you want to authenticate with. Please refer to 1 - Preparations for more details. IssueID Required This is the id of the service issue you to check the current status for. The format of the id is typically PROJECTKEY-XXX, e.g. SUP-42 Configure action exits Exit 0 (Default) This exit will be reached if an invalid issue id was given or any kind of problem occured. It is recommmended to name this exit "Invalid ID/Failed". If you reach this exit you can refer to 3.4 - Trouble Shooting to figure what went wrong. Exit 9 This exit will be reached if an unknown status was returned by the Jira REST API. It is recommended to name this exit "Unknown Status". If you reach this exit you can refer to 3.4 - Trouble Shooting to figure the returned status and modify your status mapping. Dynamic Status Mapping Jira service projects are highly flexible and depending on the selected template when you created your project and the made modifications, your project can have any number of different workflows and states. This GSE action respects this flexibility and therefore doesn't have a fixed binding of states to block exits. All block exits 1 to 8 are of your free chosing. To have something to start with, this GSE action assumes you used the Support template when you created your service project and haven't made any modifications in the workflows. This gives you a certain set of possible states, which by default are bound like this to the exits of the block: Exit States 1 Open, Waiting for support, Waiting for customer 2 Pending, In progress, Work in progress 3 Escalated 4 Canceled, Resolved, Done As already mentioned, you can modify this mapping to your precise needs. Just keep in mind that only the exits 1 to 8 are available to you. All you need to do is to modify a global variable before you use the Check Status GSE action. This can best be done in a Insert Script Code block. The content of the Insert Script Code block is then the definition of the mapping list, which is either a VBScript Array or a Lua Table. In both cases you are free to map any number of states to any exit (1..8). Lets assume you want to map your own states State A and State B to exit 5 and State C to exit 6: This is the code you need to place into the Insert Script Code block: For VBScript based call routing: UseExit = 0 g_aJiraServiceStatusMapping = Array( _ "1;Waiting for support", _ "1;Waiting for customer", _ "1;Open", _ "2;Pending", _ "2;In progress", _ "2;Work in progress", _ "3;Escalated", _ "4;Canceled", _ "4;Resolved", _ "4;Done", _ "5;State A", _ "5;State B", _ "6;State C") For Lua based call routing: UseExit = 0 g_aJiraServiceStatusMapping = { "1;Waiting for support", "1;Waiting for customer", "1;Open", "2;Pending", "2;In progress", "2;Work in progress", "3;Escalated", "4;Canceled", "4;Resolved", "4;Done", "5;State A", "5;State B", "6;State C" } As you can see, you are absolutely free in terms of the mapping of the different possible states of your service issue to an exit of the Run GSE Action block. All you need to do is to do your mapping in the Insert Script Code block and afterwards open and name the exits of the Run GSE Action block accordingly. Additional return values (as global variables) g_sLatestJiraIssueID (string) This global variable holds the ID of the latest checked issue after the ok (0) exit has been reached. g_sLatestJiraIssueStatus (string) 1.1.0 This global variable holds the status of the latest checked issue after the ok (0) exit has been reached. The A.5 - Example: Check and Announce Status makes use of this variable to announce the status via AzureTTS (text-to-speech). g_sLatestJiraIssueModified (string) 1.1.0 This global variable holds the latest modification date of the latest checked issue after the ok (0) exit has been reached. The date is as the Jira API provides it, e.g. "2024-09-03T14:48:17.138+0200". g_sLatestJiraIssueModifiedReadable (string) 1.1.0 This global variable holds the latest modification date of the latest checked issue after the ok (0) exit has been reached. The date is in a better readable format, e.g. "03.09.2024 14:48:17". The A.5 - Example: Check and Announce Status makes use of this variable to announce the latest modification date via AzureTTS (text-to-speech).

VBScript Lua This GSE action creates a new service issue. A common usage of this is to register a callback request. An example call routing script can be found in A.1 - Example: Create Issue. Configure action parameters By double clicking a parameter in the list, you can edit it. BaseURL Required This is the ase URL of your Jira Service page, for example: https://my-service.atlassian.net LoginUser Required This is the email address of the Jira user you want to authenticate with. Please refer to 1 - Preparations for more details. LoginToken Required This is the API Token of the Jira user you want to authenticate with. Please refer to 1 - Preparations for more details. ProjectKey Required When you created your Jira service project you defined a 3 character key which is used as prefix in all issue ids, for example "SUP" for your "Support" project. Summay Required This is the summary or title of the new issue. Description Required This is the description of the new issue. IssueType Required This is the type the new issue should be created with. When creating a new Jira service project you can select from many template how the project should look like, what types and states it will. You are also free to add any number of own types and states to your project. This example assumes you used the simple "Support" template and made no changes. This means, that the project has the following possible issue types: New Feature, Support, Developer escalation or Bug. This GSE action checks the issue type you enter here against the list of available/valid types, which can be modified with the next parameter, if needed. ValidIssueTypes Required When creating a new Jira service project you can select from many template how the project should look like, what types and states it will. You are also free to add any number of own types and states to your project. This example assumes you used the simple "Support" template and made no changes. This means, that the project has the following possible issue types: New Feature, Support, Developer escalation or Bug. If you modified your project you need to set the complete list of valid types here, as the GSE action checks the issue type you enter above against the types in this list. Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the service issue was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no topic has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.4 - Trouble Shooting to figure what went wrong. Additional return value (as global variable) g_sLatestJiraIssueID (string) This global variable holds ID (in PROJECTKEY-XXX format) of the newly created service issue after the ok (0) exit has been reached.

VBScript Lua This extension provides an integration of the Jira Service Management into the SwyxWare call routing. It integrates into the Jira Service Management comes for VBscript based and Lua based call routing requires SwyxWare 12.40 (or newer) for VBScript based call routing requires SwyxWare 13.10 (or newer) for Lua based call routing This integration provides the following functionality as GSE Actions within the SwyxWare call routing: Create Issue (create a new issue into an existing service project) - for example to register a callback request Add Comment (create a new comment (internal or public) to an existing service issue) Check Status (check the current status of an existing service issue) The integration makes use of the Jira REST API. Please note: Lua based call routing has been introduced to SwyxWare in version 13.10 on. As of the time of the release of the Jira Service Management Integration extension the current SwyxWare version is 14.01 and the Lua based call routing is still in BETA state and should not be used in productive environments. However, this project already comes also for Lua based call routing as an example of its ease of use. Please refer to the Forums to discuss the Jira Service Integration extension or for support requests. Please find the download for this project here. For the complete documentation explaining the setup, usage and all included examples just read the following chapters from the menu on the left. As with all other Swyx Forum Open Source Projects, Support is EXCLUSIVELY provided in the Project Froum (see link above). License Jira Service Integration v1.0.0 This is a Swyx Forum Open Source Project. https://www.swyxforum.com/projects/ https://www.swyxforum.com/jira-service-integration/introduction/0-introduction-r1/ The MIT License (MIT) Copyright (c) 2024 by Swyx Forum Copyright (c) 2024 by Tom Wellige All Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ---------------------------------------------------------------------------------------------------------------- For the VBScript based integration this project also includes the following Open Source project: JSON object class 3.5.4 - May, 29th - 2016 Licence: The MIT License (MIT) Copyright (c) 2016 RCDMK - rcdmk[at]hotmail[dot]com https://github.com/rcdmk/aspJSON https://github.com/rcdmk/aspJSON/blob/master/README.md Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Modifications needed for SwyxWare Call Routing Tom Wellige, 03.05.2017 ---------------------------------------------------------------------------------------------------------------- For the Lua based integration this project also includes the following Open Source project: Simple JSON encoding and decoding in pure Lua. Copyright 2010-2016 Jeffrey Friedl http://regex.info/blog/ Latest version: http://regex.info/blog/lua/json This code is released under a Creative Commons CC-BY "Attribution" License: http://creativecommons.org/licenses/by/3.0/deed.en_US It can be used for any purpose so long as: 1) the copyright notice above is maintained 2) the web-page links above are maintained 3) the 'AUTHOR_NOTE' string below is maintained

VBScript Lua The Invision Power Services (IPS) Integration extension writes meaningful trace information into the server trace file, according to the trace recommendation from this blog post: Don't be shy, be chatty! So, to figure the exact reason for the problem you need to take a look into that file. The following link explains where to find it and how to filter its content down to the call in question and call routing output only: How to filter SwyxWare traces for call routing output of single call Once you have opened and filtered the trace file you need to search for the first trace lines written by the GSE action. Just look for these lines: For VBScript based call routing: -------> IPS.Class_Initialize For Lua based call routing: -------> IPS:Create The following lines will contain information of all things happened, like setting the parameters and calling the IPS REST API to create the specific item. If at some point an error occurs, you will see an error message in the trace. If the REST API call fails, for example because you entered an invalid APIKey, you will see the following line: IPS web request failed! ({ "errorCode": "3S290\/7", "errorMessage": "INVALID_API_KEY" }) A list of all possible REST API errors/excaptions (and their meaning) can be taken from the IPS REST API documentation: Create Topic (POST /forums/topic) Create Post (POST /forums/posts) Create Blog Comment (POST /blog/comments) Create Download Comment (POST /downloads/comments) Create Page Comment (POST /cms/comments/{database_id}) Create Message (POST /core/messages) In addition the the error message you will also find the original response code of the web request into the REST API. If everything went fine, the response code is 201, otherwise its any other number (most likely >= 400), e.g. nResponseCode = 401 By taking the detailed error information from the server trace file you should be able to fix your problem. In case you can't get your problem fixed or have specific questions, please open your own topic in the project forum.

VBScript Lua This GSE action creates a new private message. An example call routing script can be found in A.6 - Example: CreateMessage. Configure action parameters By double clicking a parameter in the list, you can edit it. Domain Required This is the URL of your IPS community page, for example: https://www.swyxforum.com APIKey Required This is the REST API Key to authenticate against your IPS community. You created it under 1 - Preparations. Please make sure that you have configured the endpoint permissions correctly. From Required This is id of the IPS community user you want to use as sender of the message. You can obtain the id from the address line of your browser when opening that users' profile page: To Required This is id of the IPS community user you want to use asreceiver of the message. You can obtain the id from the address line of your browser when opening that users' profile page: It is possible to send the message to multiple receivers simultaneously. In this case you need to give all receiver ids in a comma separated list, e.g. 1,2,3 Please note that this will only be supported by this GSE action from SwyxWare 14.10 (or newer) on. Title Required This is the title of the new message. Body Required This is the body/text of the new message Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the message was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no message has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.7 - Trouble Shooting to figure what went wrong.

VBScript Lua This GSE action creates a new comment to a page. An example call routing script can be found in A.5 - Example: Create Page Comment. Configure action parameters By double clicking a parameter in the list, you can edit it. Domain Required This is the URL of your IPS community page, for example: https://www.swyxforum.com APIKey Required This is the REST API Key to authenticate against your IPS community. You created it under 1 - Preparations. Please make sure that you have configured the endpoint permissions correctly. Database Required This is the id of the database containing all your pages. You can obtain the id from the address line of your browser when you open the Admin Control Panel (ACP), navigate to Pages - Content - Databases and open your database. Record Required This is the id of the pagee you want to create the new comment to. You can obtain the id from the address line of your browser when opening the target page (just the number, without the leading "r"): Author Required This is id of the IPS community user you want to use as author of the new comment. You can obtain the id from the address line of your browser when opening that users' profile page: Content Required This is the content of the new comment. Hidden Should the new comment be visible to all users? 0 - the new comment will be visible to all users 1 - the new comment will be hidden, i.e. only visible to moderators and administrators, and needs approval to become visible May be omitted. Default: 0 Anonymous Should the new comment be be created as anonymous author? 0 - the new comment will be created for the above given author 1 - the new comment will be created as anyonymous author May be omitted. Default: 0 Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the page comment was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no page comment has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.7 - Trouble Shooting to figure what went wrong. Additional return value (as global variable) g_sIPSLatestCreatedPageCommentURL (string) This global variable holds the URL of the newly created page comment after the ok (0) exit has been reached.

VBScript Lua This GSE action creates a new comment to a download file. An example call routing script can be found in A.4 - Example: Create Download Comment. Configure action parameters By double clicking a parameter in the list, you can edit it. Domain Required This is the URL of your IPS community page, for example: https://www.swyxforum.com APIKey Required This is the REST API Key to authenticate against your IPS community. You created it under 1 - Preparations. Please make sure that you have configured the endpoint permissions correctly. File Required This is the id of the download file you want to create the new comment to. You can obtain the id from the address line of your browser when opening the target download file: Author Required This is id of the IPS community user you want to use as author of the new comment. You can obtain the id from the address line of your browser when opening that users' profile page: Content Required This is the content of the new comment. Hidden Should the new comment be visible to all users? 0 - the new comment will be visible to all users 1 - the new comment will be hidden, i.e. only visible to moderators and administrators, and needs approval to become visible May be omitted. Default: 0 Anonymous Should the new comment be be created as anonymous author? 0 - the new comment will be created for the above given author 1 - the new comment will be created as anyonymous author May be omitted. Default: 0 Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the download comment was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no download comment has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.7 - Trouble Shooting to figure what went wrong. Additional return value (as global variable) g_sIPSLatestCreatedDownloadCommentURL (string) This global variable holds the URL of the newly created download comment after the ok (0) exit has been reached.

VBScript Lua This GSE action creates a new comment to a blog article. An example call routing script can be found in A.3 - Example: Create Blog Comment. Configure action parameters By double clicking a parameter in the list, you can edit it. Domain Required This is the URL of your IPS community page, for example: https://www.swyxforum.com APIKey Required This is the REST API Key to authenticate against your IPS community. You created it under 1 - Preparations. Please make sure that you have configured the endpoint permissions correctly. Entry Required This is the id of the blog article you want to create the new comment in. You can obtain the id from the address line of your browser when opening the target blog article: Author Required This is id of the IPS community user you want to use as author of the new comment. You can obtain the id from the address line of your browser when opening that users' profile page: Content Required This is the content of the new comment. Hidden Should the new comment be visible to all users? 0 - the new comment will be visible to all users 1 - the new comment will be hidden, i.e. only visible to moderators and administrators, and needs approval to become visible May be omitted. Default: 0 Anonymous Should the new comment be be created as anonymous author? 0 - the new comment will be created for the above given author 1 - the new comment will be created as anyonymous author May be omitted. Default: 0 Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the blog comment was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no blog comment has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.7 - Trouble Shooting to figure what went wrong. Additional return value (as global variable) g_sIPSLatestCreatedBlogCommentURL (string) This global variable holds the URL of the newly created blog comment after the ok (0) exit has been reached.

VBScript Lua This GSE action creates a new post into an existing forum topic. An example call routing script can be found in A.2 - Example: Create Post. Configure action parameters By double clicking a parameter in the list, you can edit it. Domain Required This is the URL of your IPS community page, for example: https://www.swyxforum.com APIKey Required This is the REST API Key to authenticate against your IPS community. You created it under 1 - Preparations. Please make sure that you have configured the endpoint permissions correctly. Topic Required This is the id of the topic you want to create the new post in. You can obtain the id from the address line of your browser when opening the target topic: Author Required This is id of the IPS community user you want to use as author of the new post. You can obtain the id from the address line of your browser when opening that users' profile page: Post Required This is the text/body of the new topic. Hidden Should the new post be visible to all users? 0 - the new post will be visible to all users 1 - the new post will be hidden, i.e. only visible to moderators and administrators, and needs approval to become visible May be omitted. Default: 0 Configure action exits Exit 0 (Default) This exit will be reached when everyhting worked fine and the post was created. It is recommmended to name this exit "ok" or "created". Exit 1 This exit will be reached when there was any kind of problem and no post has been created. It is recommended to name this exit "failed". If you reach this exit you can refer to 3.7 - Trouble Shooting to figure what went wrong. Additional return value (as global variable) g_sIPSLatestCreatedPostURL (string) This global variable holds the URL of the newly created post after the ok (0) exit has been reached.