Tom Wellige

Lua SwxWare v13.10 This helper function takes a string or a number (converts it into a string) and adds leading zeros ("0") until a given length is reached. local sNumber = AddLeadingZeros(szSource, nExpectedNumberLength) This functions returns a string value. Example: local nNumber = 2 local sNumber = AddLeadingZeros(nNumber, 4) PBXScript.OutputTrace("sNumber = " .. sNumber) --> sNumber = 0002

Lua → VBScript SwxWare v13.10 In order to communicate from ECR scripts with web services of all kinds, the Lua integration offers a dynamically embeddable module based on the proven curl library. This module is not loaded by default because this does not unnecessarily increase the resource requirements of the Lua runtime environment. Functions offered by this module Execute all well-known request types: GET, POST, PUT, PATCH, DELETE und HEAD Support of most common HTTP-Auth methods: Basic, Digest und Bearer Add any header to the request in text form Add any URL parameter with build-in escaping Retrieve all header from requests and reponses Automatic conversion of the response body to a Lua string based on the 'Contenttype' header Requests can be made either via encrypted or unencrypted connections. This is selected by URL ("https:// ..." oder "http:// ..."). In addition, certificate validation can be disabled in the case of internal web services with self-signed certificates. Howto use the module The integration into an ECR script is done with the usual Lua mechanism by means of the keyword 'require' placed in an 'InsertScript'-Block local webreq = require "PBXWebRequest" The webreq object now can be used to create one or more independent HTTP session objects. New HTTP session objects are preset to HTTP Verb GET with no authentication and certification validation is active. Additional note: the webreq should always be checked for 'nil' to avoid potential run-time errors. if (webreq ~= nil) then local hsession1, hsession2 hsession1 = webreq.new() hsession2 = webreq.new() -- a second HTTP Session object to perform an additional query in parallel end Here is an example as overview - the detailed description of the API can be found below this example. local webreq = require "PBXWebRequest" if (webreq ~= nil) then local hsession, reponseCode, responseHeaders, encodedURL PBXScript.OutputTrace("Web request loaded...") hsession = webreq.new() hsession:URL("https://example.org") hsession:HttpVerb(PBXHttpVerbGet) hsession:AddHeader("Content-Type:application/json; charset=UTF-8") hsession:AddQueryPair("artist", "Simon & Garfunkel") hsession:AddQueryPair("callid", PBXCall.CallId()) hsession:AddQueryPair("callernumber", PBXCall.CallingPartyNumber()) hsession:AddQueryPair("callername", PBXCall.CallingPartyName()) -- hsession:HttpAuth = HttpAuthBasic -- hsession:AuthUser = "foo" -- hsession:AuthPass = "bar" hsession:VerifyPeer(true) requestHeaders = hsession:RequestHeaders() for i = 1, #requestHeaders do PBXScript.OutputTrace(" [" .. i .. "] " .. requestHeaders[i]) end responseCode = hsession:Execute() PBXScript.OutputTrace("Web request response " .. responseCode) if (responseCode == 200) then responseHeaders = hsession:ResponseHeaders() for i = 1, #responseHeaders do PBXScript.OutputTrace(" [" .. i .. "] " .. responseHeaders[i]) end end end A complete usage example can be found in the Zendesk Integration project (incl. Json formatted data handling), which is part of the Open ECR Extensions project here on Swyx Forum. Another more simple example is the LaunchHTTPRequest() function from the Function Collection. Description of WebReq Object API Some enum values used as parameter HTTP Verbs PBXHttpVerbGetto execute a GET request (default) PBXHttpVerbPost to execute a POST request PBXHttpVerbPut to execute a PUT request PBXHttpVerbDelete to execute a DELETE request PBXHttpVerbPatch to execute a PATCH request PBXHttpVerbHead to execute a HEAD request HTTP Authentication PBXHttpAuthNone no authentication used for request (Default) PBXHttpAuthBasic HTTP basic authentication by username and password according to RFC7617 PBXHttpAuthDigest HTTP digest authentication by username and password according to RFC7616 PBXHttpAuthBearer HTTP bearer authentication by OAuth 2.0 bearer access token provided via password property PBXHttpAuthAny automatic negotiation which authentication mechanism to use API Methods The following methods set the respective value when it is passed as a parameter, or return the current value set if the method is called without parameters. Note: all examples assume a HTTP session variable with the name hsession! HttpVerb(<verb enum>) Set HTTP Verb by enum value. To set: hsession:HttpVerb(PBXHttpVerbPost) To retrieve: verb = hsession:HttpVerb() HttpAuth(<auth enum>) Set HTTP authentication method to use. To set: hsession:HttpAuth(PBXHttpAuthBasic) To retrieve: auth = hsession:HttpAuth() AuthUser("<user name>") Set user name to use with authentication. To set: hsession:AuthUser("<user name>") To retrieve: user = hsession:AuthUser() AuthPass("<password>") Set password to use with authentication. To set: hsession:AuthPass("<password>") To retrieve: password = hsession:AuthPass() VerifyPeer(<true/false>) Activate or deactivate validation of TLS certificate. 'true' = check is active, 'false' = check is deactivated. hsession:VerifyPeer(false) Url("<url string >") Sets the URL for the request. The choice between encrypted or unencrypted is made via the URL in the form "https:// ..." oder "http:// ...". To set: hsession:URL("https://example.org") To retrieve: url = hsession:URL() Additional functions UrlEncode("<string to encode>") Convert given string according to URL escaping rules as of https://en.wikipedia.org/wiki/URL-Encoding Return value: string URL encoded url_encoded = hsession:URLEncode("Dörte Weiß sucht das Glück") AddHeader("<header string>") Sets any header as text Return value: none hsession:AddHeader("Content-Type:application/json; charset=UTF-8") AddQueryPair("<key>", "<value>") Set key/value pair to use in request URL Return value: none hsession::AddQueryPair("artist", "Simon & Garfunkel") RequestBody("<body text>") Sets any request body text or returns the currently set text (blank string if no text has been set) To set: hsession:RequestBody("<h1>My body text</h1>") To retrieve: body = hsession:RequestBody() RequestHeaders() Return current list of request header(s) as Lua table or nil. No input parameter supported! Return value: Lua table or 'nil' headers = hsession:RequestHeaders() ResponseBody() Return last response body text or blank string. No input parameter supported! respBody = hsession:ResponseBody() ResponseHeaders() Return current list of response header(s) as Lua table or nil. No input parameter supported! Return value: Lua table or 'nil' respBody = hsession:ResponseHeaders() Execute() Execute web request with given parameters. No input parameter supported! Return value: response code from request as number. Will be 200 on successful request or any value according to HTTP spec. resp = hsession:Execute() Reset() Resets the HTTP Session object back to its initial state. The HTTP verb is GET without authentication and certificate validation is enabled. Return value: none hsession:Reset() Tracing To diagnose a problem the following trace modules of SwyxWare-Server can be used: SrvScrAPI set to 6 to get detailed tracing for API calls SrvScrWeb set to 6 to get detailed tracing for any web request Final notes Two timeout values are fixed and can‘t be changed dynamically: Maximum time for establishing a connection to the web service is 10s. Maximum time for web service to respond is 10s The http proxy settings are read and applied by the system.

Lua SwxWare v13.10 This function returns the version of the Server Script API. local nVersion = PBXScript.Version() This function returns a number value.

Lua → VBScript SwxWare v13.10 Returns the Locale ID (LCID) of the language the current Windows OS is installed in, meaning it tells you the language of the installed Windows. -- is this a french Windows ? if (PBXScript.SystemLanguageID() == 1036) then -- do something end This property returns a number value. The following is a list of all LCIDs of the current/former language versions of the SwyxWare: Language hex value decimal value short string ---------- --------- ------------- ------------ Danish 0x0406 1030 dk Dutch 0x0813 1043 nl English UK 0x0809 2057 en-GB French 0x040C 1036 fr German 0x0407 1031 de Italian 0x0410 1040 it Norwegian 0x0414 1044 no Spanish 0x0C0A 3082 es Using the PBXScript.InstallLanguageId() function you can additionally request the LCID of the installed Windows OS. A complete list of all existing LCIDs can be found within the MSDN.

Lua → VBScript SwxWare v13.10 This function stops the execution of the current script for the given number of milliseconds. PBXScript.Sleep(1000) This function returns a PBXResult value of PBXSuccess. The numeric parameter gives the number of milliseconds to "sleep". This function is used to wait a certain amount of time without consuming any CPU load. A common usage is e.g. in a call queue to check every second for the availability of a free agent. While "sleeping" one second no cpu load is used. When ever you need to loop within your script make sure to use this function to slow the execution of the loop down and save cpu load. An endless loop, like while true do i = i + 1 end will drive the CPU load of the server machine to 100% and therefore interfere negatively with all calls on and other activities of the SwyxServer. So, whenever you need to do something like the above, you need to slow the loop down. while true do i = i + 1 PBXScript.Sleep(1000) end

Lua → VBScript SwxWare v13.10 This function sends an email containing the given information. local nReturn = PBXScript.SendEMail(sSender, sReplyTo, sRecipients, sCC, sBCC, sSubject, sBody, sAttachmentFile, sAttachmentMimeType, bIsVoicemail) This function returns a PBXResult value of PBXSuccess or PBXFailure. You can also use the PBXCall.SendEMail() function if you don't need all these additional standard email fields like CC and BCC. Parameters sSender string. The EMail "From" field. sReplyTo string. The EMail "ReplyTo" field. sRecipients string. The EMail "To" field. Can contain multiple email addresses, separated by ";" (semicolon). sCC string. The EMail "CC" field. sBCC string. The EMail "BCC" field. sSubject string. The EMail "Subject" field. sBody string. The EMail "Body" field. sAttachmentFile string. Filename (incl. complete path) to attach to this email. sAttachmentMimeType string. Mime Type fo attached file. bIsVoicemail boolean. Flag this email as SwyxWare "voicemail" via X-Header.

Lua → VBScript SwxWare v13.10 This function returns a list (indexed table) with information about all call routing scripts the call was in before reaching the current one. local tScripts = PBXScript.PreviousScripts() This function returns an indexed table with the following content per entry: userid (obsolete from SwyxWare v13.27, contains valid value for user scripts only) username (obsolete from SwyxWare v13.27, contains valid value for user scripts only) entitytype (new from SwyxWare v13.27) either PBXScriptTypeUser or PBXScriptTypeGroup entityid (new from SwyxWare v13.27) number value containing the SwyxWare interal id of user or user group entityname (new from SwyxWare v13.27) string value containing the name of user or user group start end [ { .userid : number .username : string .entitytype : number .entityid : number .entityname : string .start : { .sec : number .min : number .hour : number .day : number .month : number .year : number .wday : number .yday : number .isdst : boolean } .finish : { .sec : number .min : number .hour : number .day : number .month : number .year : number .wday : number .yday : number .isdst : boolean } } ] Please note, that the date and time is given in Universal Time Coordinated (UTC), so it comes without any daylight savin time problems. The follwing example lists all available information into the Server trace file: local tScripts = nil tScripts = PBXScript.PreviousScripts() if (tScripts ~= nil) then for i = 1, #tScripts do -- til SwyxWare v13.26 PBXScript.OutputTrace("UserId: " .. tScripts[i].userid) PBXScript.OutputTrace("UserName: " .. tScripts[i].username) -- from SwyxWare v13.27 PBXScript.OutputTrace("EntityType: " .. tScripts[i].entitytype) PBXScript.OutputTrace("EntityId : " .. tScripts[i].entityid) PBXScript.OutputTrace("EntityName : " .. tScripts[i].entityname) PBXScript.OutputTrace("StartTime: " .. AddLeadingZeros(tScripts[i].start.day, 2) .. "." .. AddLeadingZeros(tScripts[i].start.month, 2) .. "." .. AddLeadingZeros(tScripts[i].start.year, 4) .. " " .. AddLeadingZeros(tScripts[i].start.hour, 2) .. ":" .. AddLeadingZeros(tScripts[i].start.min, 2) .. ":" .. AddLeadingZeros(tScripts[i].start.sec, 2)) PBXScript.OutputTrace("EndTime: " .. AddLeadingZeros(tScripts[i].finish.day, 2) .. "." .. AddLeadingZeros(tScripts[i].finish.month, 2) .. "." .. AddLeadingZeros(tScripts[i].finish.year, 4) .. " " .. AddLeadingZeros(tScripts[i].finish.hour, 2) .. ":" .. AddLeadingZeros(tScripts[i].finish.min, 2) .. ":" .. AddLeadingZeros(tScripts[i].finish.sec, 2)) end end This example makes use of the string helper function AddLeadingZeros() from the GSE build-in helper functions. Resulting trace lines if call was forwarded by one previous user: Til SwyxWare v13.26 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () UserId: 20 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () UserName: Erika Mustermann 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () StartTime: 04.06.2022 16:18:00 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () EndTime: 04.06.2022 16:18:20 From SwyxWare v13.27 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () EntityType: 1 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () EntityId: 20 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () EntityName: Erika Mustermann 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () StartTime: 04.06.2022 16:18:00 04 18:18:23.840 001e70 Info SrvScript 0942A7E8 00000084 SPBXScriptLua::OutputTrace () EndTime: 04.06.2022 16:18:20 Examples from the Function Collection IsCallTransferred() IsRedirectedFromByName() (til SwyxWare v13.26) IsRedirectedFromByNameEx() (from SwyxWare v13.27) IsRedirectionLoopConfigured()

Lua → VBScript SwxWare v13.10 This function can be used to write trace outout into SwyxServer's trace file. Tracing can be used for debugging of realtime systems and is highly recommended to be used within own script code. PBXScript.OutputTraceEx(PBXScriptTraceLevel, "Hello World") This function can be used at any time within a call routing script. The string being passed as parameter will be directly written into the SwyxServer trace file. The first parameter of type PBXScriptTraceLevel defines the trace level. The trace message is logged only if the configured trace level (see below) is higher or equal as the level specified in the trace statement. The following trace levels are defined: PBXScript.TraceError = 2 PBXScript.TraceWarn = 3 PBXScript.TraceInfo = 4 PBXScript.TraceInfo2 = 5 PBXScript.TraceInfo3 = 6 This function provides the ability to write trace output on any trace level, e.g. Warn or Error, instead of the default level TraceInfo3 which is used by the PBXScript.OutputTrace() function. The following blog article provides some general hints about tracing within call routing: The Call Routing Guy - #3: Don't by shy, be chatty! The following article explains how to filter one single call from a SwyxServer trace file, and from that call only the call routing relevant trace lines: How to filter SwyxWare traces for call routing output of single call

Lua → VBScript SwxWare v13.10 This function can be used to write trace out into the SwyxServer's trace file. Tracing can be used for debugging of realtime systems and is highly recommended to be used within own script code. PBXScript.OutputTrace("Hello World") This function returns always PBXResult value of PBXSuccess. This function can be used at any time within a call routing script. The string being passed as parameter will be directly written into the SwyxServer trace file. Call routing traces will be written by the SrvScript module of IpPbxSrv to Info3 level. To create trace output on any trace level you can use PBXScript.OutputTraceEx(). The following blog article provides some general hints about tracing within call routing: The Call Routing Guy - #3: Don't by shy, be chatty! The following article explains how to filter one single call from a SwyxServer trace file, and from that call only the call routing relevant trace lines: How to filter SwyxWare traces for call routing output of single call

Lua → VBScript SwxWare v13.10 Returns the Locale ID (LCID) of the language the SwyxWare is installed in, meaning it tells you the language of the installed SwyxWare. -- is this a french SwyxWare ? if (PBXScript.InstallLanguageID() == 1036) then -- do something end This property returns a number value. The following is a list of all LCIDs of the current/former language versions of the SwyxWare: Language hex value decimal value short string ---------- --------- ------------- ------------ Danish 0x0406 1030 dk Dutch 0x0813 1043 nl English UK 0x0809 2057 en-GB French 0x040C 1036 fr German 0x0407 1031 de Italian 0x0410 1040 it Norwegian 0x0414 1044 no Spanish 0x0C0A 3082 es Using the PBXScript.SystemLanguageId() function you can additionally request the LCID of the installed Windows OS. A complete list of all existing LCIDs can be found within the MSDN.

Lua → VBScript SwxWare v13.10 This function searches for a user or multiple users and returns its results as list (indexed table). local oUsers = PBXScript.GetUserByAddress(sNumber) This function returns an indexed table with PBXConfigUser elements. Parameter sNumber string. An internal number of a user or group, user name, group name, H.323 alias or SIP user ID to search for. The result PBXConfigUser element contains a number of information regarding the found user: :UserID() : number :Name() : string :EMailAddress() : string :State() : number, PBXUserState (see PBXConfigUser) :DataFolder() : string (***obsolete***) :Numbers() : indexed table of strings :MobileIdentificationNumbers() : indexed table of strings (***obsolete***) :IsMobileExtensionEnabled() : boolean (***obsolete***) :MobilePhoneNumber() : string (***obsolete***) :NumberOfNewVoicemails() : number :FreeStatusText() : string The following is an example making use of the PBXScript.GetUserByAddress() function to return the current status of a given user: ------------------------------------------------------------------ -- GetUserStatus -- -- Returns the status of the given user. -- If being used on a user group it returns the status of the last user in the group. -- -- Parameter: -- sNumber extension of user or user group -- -- Return: -- number - PBXUserStateValue -- -- PBXUserStateUnavailable = 0 -- PBXUserStateLoggedOff = 1 -- PBXUserStateLoggedOn = 2 -- PBXUserStateSpeakingExternal = 3 -- PBXUserStateAlerting = 4 -- PBXUserStateSpeakingInternal = 5 -- PBXUserStateAway = 6 -- PBXUserStateDoNotDisturb = 7 -- PBXUserStateActive3rdParty = 8 ------------------------------------------------------------------ function GetUserStatus(sNumber) PBXScript.OutputTrace ("-------------> GetUserStatus(sNumber = " .. sNumber .. ")") local nReturn = 0 local oUsers = nil oUsers = PBXScript.GetUserByAddress(sNumber) if (oUsers ~= nil) then for i = 1, #oUsers do PBXScript.OutputTrace ("Found user " .. oUsers[i]:Name() .. " with current state " .. oUsers[i]:State()) nReturn = oUsers[i]:State() end end PBXScript.OutputTrace ("nReturn = " .. nReturn) PBXScript.OutputTrace ("<------------- GetUserStatus") return nReturn end Examples from the Function Collection :Name() GetUserNameFromExtension() IsUserInGroup() :State() GetUserStatus() IsAtLeastOneMemberOfGroupBusy() IsAtLeastOneMemberOfGroupLoggedOff() IsGroupLoggedOff() IsUserFree() IsUserLoggedOff() IsUserLoggedOn() :NumberOfNewVoicemails() SetNewVoicemailFlag()

Lua → VBScript SwxWare v13.10 This function returns a table containing general SwyxWare configuration information. local tConfig = PBXScript.GetPBXConfig() This function returns a table value. Following fields are included in the returned table: .countrycode : string .areacode : string .longdistancecallprefix : string .internationalcallprefix : string .publicaccessprefix : string .numberrangestart : string .numberrangeend : string .nondeliverablecallsnumber : string .voicemailfromaddress : string Example from the Function Collection IsExternalRedirectionConfigured()

Lua → VBScript SwxWare v13.10 This function returns the length of a given .wav file in seconds. local nLength = PBXScript.GetAudioFileLength(sFileName) This function returns a number value. If 0 is returned, the file length is 0 or length could not be determined, e.g. because of an unsupported file format. SwyxWare requires .wav files in 16kHz, 16bit, mono format. local nLength = PBXScript.GetAudioFileLength("Welcome.wav") If no explicit path is given in sFileName, SwyxServer searches this file in the database, in the following scopes in that order: User User Default Global System Default local nLength = PBXScript.GetAudioFileLength("C:\Announcements\Welcome.wav") It is also possible to use a local file from the SwyxServer machine. In this case it is necessary, that the Windows user account the SwyxServer service is running under (usually the SwyxServiceAccount), has read privileges on that file.

Lua → VBScript SwxWare v13.10 This function ends any scripting for the current call immediately. PBXScript.EndScript() This function has no return value. Script is ended immediately. After this statement no further script statements are executed. The current call will be disconnected if it is not successfully connected to a destination before.

Lua → VBScript SwxWare v13.10 This function converts a given extension into a full canonical number. PBXScript.ConvertToCanonical ( sExtension ) This function returns a string value. Parameter sExtension string. The number/extension to conert into canonical format. Example SwyxServer has the following configuration: Countrycode 49 Areacode 231 Subscribernumber 4777 local sCanonicalNumber = PBXScript.ConvertToCanonical("180") PBXScript.OutputTrace("sCanonicalNumber = ", sCanonicalNumber) --> +492314777180

Lua → VBScript SwxWare v13.10 This function returns either true or false if a certain number is completely or partly given in another number respective list of numbers. PBXScript.CompareNumbers(sNumber, sNumberList) This function returns a boolean value. Parameters sNumber string. The number to search for. sNumberList string. The list of numbers to search sNumber in. It is possible to use the wildcard * (asterisk) as placeholder for any following digit respective number of digits. A ; (semicolon) in the number list separates different numbers. Example local sNumberList = "49231477733*;34*" if (PBXScript.CompareNumbers("333", sNumberList) == true) then -- do something end This example returns true as "333" is in fact part of the number list, "49231477733*".