Find

Article
· Dec 20, 2023 11m read

Leveraging your InterSystems Login Account to Up your Technical Game

#Authentication #Best Practices #Cloud #Deployment #GitHub #Languages #ObjectScript #Tools #Other

Your may not realize it, but your InterSystems Login Account can be used to access a very wide array of InterSystems services to help you learn and use InterSystems IRIS and other InterSystems technologies more effectively.  Continue reading to learn more about how to unlock new technical knowledge and tools using your InterSystems Login account.  Also - after reading, please participate in the Poll at the bottom, so we can see how this article was useful to you!

What is an InterSystems Login Account? 

An InterSystems Login account is used to access various online services which serve InterSystems prospects, partners, and customers.  It is a single set of credentials used across 15+ externally facing applications.  Some applications (like the WRC, or iService) require specific activation for access to be granted by the account.  Chances are there is are resources which will help you but you didn't know about - make sure to read about all of the options and try out a new tool to help up your technical game!!

Application Catalog

You can view all services available to you with your InterSystems Login account by visiting that InterSystems Application Catalog, located at:  https://Login.InterSystems.com.  This will list only those applications or services to which you currently have access.  It remembers your most frequently used applications and lists them at the top for your convenience. 

Make sure to Bookmark the page for easy access to all of these tools in your InterSystems Login Account toolbox!

Application Details 

Now it's time to get into the details of the individual applications and how they can help you as a developer working with InterSystems technologies!  Read on and try to find a new application to leverage for the first time in order to improve your efficiency and skills as a developer....

 Getting Started - gettingstarted.intersystems.com 

Audience

  • Anyone wishing to explore using InterSystems IRIS® data platform

Description

  • Learn how to build data-intensive, mission-critical applications fast with InterSystems IRIS.
  • Work through videos and tutorials leveraging SQL, Java, C#/.Net, Node.js, Python, or InterSystems ObjectScript.
  • Use a free, cloud-based, in-browser Sandbox -- IRIS+IDE+Web Terminal—to work through tutorials. 

How it helps Up Your Technical Game

  • Quickly get oriented with InterSystems technology and see it in action with real working code and examples!
  • Explore the use of other popular programming languages with InterSystems IRIS.

 Online Learning - learning.intersystems.com

Audience

  • All users and potential users of InterSystems products 

Description

  • Self-paced materials to help you build and support the world's most important applications:
    • Hands-on exercises
    • Videos
    • Online Courses
    • Learning Paths

How it helps Up Your Technical Game

  • Learn, learn, learn!! 
  • Nothing will help you become a more effective developer faster than following a skilled technical trainer as they walk you through new concepts to use in your InterSystems IRIS projects! 

 Documentation - docs.intersystems.com 

Audience

  • All users and potential users of InterSystems products

Description

  • Documentation for all versions of our products
  • Links where needed to external documentation
  • All recent content, is fed through our new search engine.
  • Search page lets you filter by product, version, and other facets.
  • Certain docs require authorization (via InterSystems Login account):
    • AtScale docs available to Adaptive Analytics customers
    • HealthShare docs are available to HealthShare users
  • Make sure to make use of the new dynamic Upgrade Impact Checklist within the Docs server!

How it helps Up Your Technical Game

  • Quickly make use of class reference material and API documentation.
  • Find example code. 
  • Read detailed usage documentation for parts of InterSystems IRIS into which you need a deeper dive.
  • Request additional detail or report issues direct from within the documentation pages via the "Feedback" feature.

 Evaluation - evaluation.intersystems.com

Audience

  • Those wishing to download InterSystems software or licenses for evaluation or development use

Description

  • Downloads of InterSystems IRIS and InterSystems IRIS for Health.
  • Anybody can download Community Edition kits.
  • Existing customers can also request a powerful license to evaluate enterprise features.
  • Preview versions are available pre-release.
  • Early Access Program packages allow people to provide feedback on future products and features.

How it helps Up Your Technical Game

  • Try out Preview versions of software to see how new features can help to accelerate your development.
  • Test run Enterprise features by requesting an evaluation license.
  • Make sure all developers in your organization have the latest version of InterSystems IRIS installed on their machines.
  • Provide feedback to InterSystems Product Management about Early Access Features to ensure that they will meet your team's needs once they are fully released.

 Developer Community - community.intersystems.com

Audience

  • Anyone working with InterSystems technology (InterSystems employees, customers, partners, and prospects)

Description

  • Monitor announcements related to InterSystems products and services.
  • Find articles on a variety of technical topics.
  • Ask questions and get answers from the community.
  • Explore job postings or developers available for hire.
  • Participate in competitions featuring $1000’s in cash prizes.
  • Stay up to date concerning all things InterSystems!

How it helps Up Your Technical Game

  • With access to the leading global experts on InterSystems technology, you can learn from the best and stay engaged with the hottest questions, trends and topics.
  • Automatically get updates in your inbox on new products, releases, and Early Access Program opportunities.
  • Get help from peers to answer your questions and move past blockers.
  • Have enriching discussions with InterSystems Product Managers and Product Developers - learn from the source!
  • Push your skills to the next level by sharing technical solutions and sharing code and gaining from feedback from others.

 InterSystems Ideas - ideas.intersystems.com

Audience

  • Those looking to share ideas for improving InterSystems technology.

Description

  • Post ideas on how to make InterSystems technology better.
  • Read existing reviews and up-vote or engage in discussions.
  • InterSystems will take the most popular ideas into account for future product roadmaps.

How it helps Up Your Technical Game

  • See your ideas and needs turned into a reality within InterSystems products or open source libraries.
  • Become familiar with the ideas of your peers and learn to use InterSystems products in new ways.
  • Implement ideas suggested by others, new exploring parts of InterSystems technology.

 Global Masters - globalmasters.intersystems.com

Audience

  • Those wishing to advocate for InterSystems technology and earn badges and swag

Description

  • Gamification platform designed for developers to learn, stay up-to-date and get recognition for contributions via interactive content.
  • Users receive points and badges for:
    • Engagement on the Developer Community
    • Engagement on the Open Exchange
    • Publishing posts to social media about InterSystems products and technologies
  • Trade in points for InterSystems swag or free training

How it helps Up Your Technical Game

  • Challenges bring to your attention articles or videos which you may have missed on the Developer Community, Learning site or YouTube channel - constantly learning new things to apply to your projects!

 Open Exchange - openexchange.intersystems.com 

Audience

  • Developers seeking to publish or make use of reusable software packages and tools

Description

  • Developer tools and packages built with InterSystems data platforms and products. 
  • Packages are published under a variety of software licenses (mostly open source).
  • Integrated with GitHub for package versioning, discussions, and bug tracking.
  • Read and submit reviews and find the most popular packages.
  • Developers can submit issues and make improvements to packages via GitHub pull requests to help push community software forward.
  • Developers can see statistics of traffic and downloads of the packages they published

How it helps Up Your Technical Game

  • Don't reinvent the wheel!  Use open source packages created and maintained by the InterSystems Community to solve generic problems, leaving you to focus on developing solutions needed specifically by your business.
  • Contributing to open source packages is a great way to receive constructive feedback on your work and refine your development patterns.
  • Becoming a respected contributor to open source projects is a great way to see demand increase for your skills and insights. 

 WRC - wrc.intersystems.com

Audience

  • Issue tracking system for all customer reported problems on InterSystems IRIS and InterSystems HealthShare.  Customers with SUTA can work directly with the application.

Description

  • Worldwide Response Center application (aka “WRC Direct”).
  • Issue tracking system for all customer reported problems. 
  • Open new requests. 
  • See all investigative actions and add information and comments about a request. 
  • See statistical information about your support call history. 
  • Close requests and provide feedback about the support process. 
  • Review ad-hoc patch files. 
  • Monitor software change requests.
  • Download current product and client software releases.

How it helps Up Your Technical Game

  • InterSystems Support Engineers can help you get past any technical blocker you have concerning development or systems management with InterSystems products.
  • Report bugs to ensure that issues are fixed in future releases.  

 iService - iservice.intersystems.com

Audience

  • Customers requiring support under an SLA agreement

Description

  • A support ticketing platform for our healthcare, cloud and hosted customers.
  • Allows for rule driven service-level agreement (SLA) compliance calculation and reporting.
  • Provides advanced facet search and export functionality. 
  • Incorporates a full Clinical Safety management system.

How it helps Up Your Technical Game

  • InterSystems Support Engineers can help you get past any technical blocker you have concerning development or systems management with InterSystems healthcare or cloud products.
  • Report bugs to ensure that issues are fixed in future releases.  

 ICR - containers.intersystems.com

Audience

  • Anyone who wants to use InterSystems containers

Description

  • InterSystems Container Registry
  • A programmatically accessible container registry and web UI for browsing.
  • Community Edition containers available to everyone.
  • Commercial versions of InterSystems IRIS and InterSystems IRIS for Health available for supported customers.
  • Generate tokens to use in CICD pipelines for automatically fetching containers.

How it helps Up Your Technical Game

  • Increase the maturity of your SDLC by moving to container-based CICD pipelines for your development, testing and deployment!

 Partner Directory - partner.intersystems.com 

Audience

  • Those looking to find an InterSystems partner or partner’s product 
  • Partners looking to advertise their software and services  

Description

  • Search for all types of InterSystems partners:
    • Implementation Partners
    • Solution Partners
    • Technology Partners
    • Cloud Partner
  • Existing partners can manage their service and software listings. 

How it helps Up Your Technical Game

  • Bring in certified experts on a contract basis to learn from them on your projects.
  • License enterprise solutions based on InterSystems technology so you don't have to build everything from scratch.
  • Bring your products and services to a wider audience, increasing demand and requiring you to increase your ability to deliver!

 CCR - ccr.intersystems.com 

Audience

  • Select organizations managing changes made to an InterSystems implementation (employees, partners and end users)

Description

  • Change Control Record
    • Custom workflow application built on our own technology to track all customizations to InterSystems healthcare products installed around the world.
  • Versioning and deployment of onsite custom code and configuration changes.
  • Multiple Tiers and workflow configuration options.
  • Very adaptable to meet the specific needs of the phase of the project

How it helps Up Your Technical Game

  • For teams authorized for its use, find and reuse code or implementation plans within your organization, preventing having to solve the same problem multiple times.
  • Resolve issues in production much more quickly, leaving more time for development work. 

 Client Connection - client.intersystems.com  

Audience

  • Available to any TrakCare clients

Description

  • InterSystems Client Connection is a collaboration and knowledge-sharing platform for TrakCare clients.
  • Online community for TrakCare clients to build more, better, closer connections.
  • On Client Connection you will find the following: 
    • TrakCare news and events 
    • TrakCare release materials, e.g. release documentation and preview videos
    • Access to the most up-to-date product guides.
    • Support materials to grow personal knowledge.
    • Discussion forums to leverage peer expertise. 

How it helps Up Your Technical Game

  • Technical and Application Specialists at TrakCare sites can share questions and knowledge quickly - connecting with other users worldwide.  Faster answers means more time to build solutions!

 Online Ordering - store.intersystems.com

Audience

  • Operations users at selected Application partners/end-users

Description

  • Allow customers to pick different products according to their contracts and create new orders.  
  • Allow customers to upgrade/trade-in existing orders.
  • Submit orders to InterSystems Customer Operations to process them for delivery and invoicing.
  • Allow customers to migrate existing licenses to InterSystems IRIS.

How it helps Up Your Technical Game

  • Honestly, it doesn't!  It's a tool used by operations personnel and not technical users, but it is listed here for completeness since access is controlled via the InterSystems Login Account ;)  

Other Things to Know About your InterSystems Login Account

Here are a few more useful facts about InterSystems Login Accounts...

How to Create a Login Account

Users can make their own account by clicking "Create Account" on any InterSystems public-facing application, including:

Alternatively, the InterSystems FRC (First Response Center) will create a Login Account for supported customers the first time they need to access the Worldwide Response Center (WRC) or iService (or supported customers can also create accounts for their colleagues).

Before using an account, a user must accept the Terms and Conditions, either during the self-registration process or the first time they log in.

Alternative Login Options

Certain applications allow login with Google or GitHub:

This is the same InterSystems Login Account, but with authentication by Google or GitHub.

Account Profile

If you go to https://Login.InterSystems.com and authenticate, you will be able to access Options > Profile and make basic changes to your account.  Email can be changed via Options > Change Email.  

Resolving Login Account Issues

Issues with InterSystems Login Accounts should be directed to Support@InterSystems.com.  Please include:

  • Username used for attempted login
  • Email
  • Browser type and version
  • Specific error messages and/or screenshots
  • Time and date the error was received   
4 Comments
Discussion (4)1
Log in or sign up to continue
Question
· Dec 20, 2023

How to decode the binary data produced by in the event log ?

#Web Gateway #InterSystems IRIS

I am using the event logger from CSP gateway with level "v9r" enabled, in order to dump the raw content of some HTTP requests.

I would like to decode the body response data, when it's in binary form. AFAIK the event logger will convert characters outside the 32-127 range (EBCDIC) to the "\xff" notation (where ff is a hexadecimal value). Here is an example :

Content What is written in the log Remark
helloworld helloworld  
hello £ world hello \xc2\xa3 world £ is C2A3 in Unicode
hello \xc2\xa3 world hello \xc2\xa3 world same as line above !

The way it works seems to be (pseudocode) :

for (int data : byteBuffer) {
    if (data >= 32 && data <= 127) {
        output((char)data);
    } 
    else { 
        output("\x" + toHex(data));
    }
}

The main issue is data is just left as it is if it already contains any \x characters inside (which occurs very often with GZIP content). AFAIK this make any decoding impossible. Is there a way to fix this ? (by specifying the event logger should use another format, or should uncompress GZIP content before dump).

EDIT : Apache use a similar way to encode binary data to EBCDIC when dumping HTTP content, but it escapes data correctly :

hello £ world hello \xc2\xa3 world
hello \xc2\xa3 world hello \\xc2\\xa3 world

Unless I miss something, IRIS implementation is incorrect.

4 Comments
Discussion (4)1
Log in or sign up to continue
Article
· Dec 9, 2023 3m read

Working Around SOAP Service Timeouts

#Best Practices #InterSystems IRIS

Some of our applications provide SOAP services that use “DSTIME”-based SQL queries that return records that have recently been added or changed. Since the records don’t change often, these queries usually return a small number of records and therefore take little time.

However, we sometimes make a table change that affects all records in that table. When that happens, on the next SOAP request from a SOAP client the service will run its query which will take an extra-long time because all records are included (for our apps, the queries return hundreds of thousands of records in this case).

The amount of time for producing the results therefore sometimes exceeds the default “timeout” specified in the CSP gateway connection for the instance hosting the SOAP service. This results in the connection being closed before the client gets its requested data and the client instead gets an error message like the following:

ERROR #5002: ObjectScript error: InvokeClient+208^%SOAP.WebClient.1

We can confirm the error is due to a timeout by viewing SOAP error details on the client using the “InterSystems IRIS SOAP Log” feature described here.

The following output from the log file confirms the timeout error:

Input to Web client with SOAP action = http://www.intersystems.com/user/SOAPTest.SlowSOAPService.GetSlowService

ERROR #5922: Timed out waiting for response
string**** SOAP client return error. method=GetSlowService, action=http://www.intersystems.com/user/SOAPTest.SlowSOAPService.GetSlowService
     ERROR #5922: Timed out waiting for response

To address this error, we added code to set a connection timeout to the instance of the SOAP client before calling the SOAP method that uses that one query. We had run the query on the Management Portal’s SQL page, writing the output to a csv file, and noted that it took over 6 minutes to complete. We therefore added this code to increase the timeout to 10 minutes before calling the service (the names were changed to protect the innocent 😊):

    #dim result As %XML.DataSet
    set wc = ##class(SlowSOAPService.WebClient.SlowSOAPServiceSoap).%New()
    set sc = wc.TimeoutSet(600)
    set sc = wc.GetSlowService(.result)

The %SOAP.WebService class provides the “TimeoutSet” method that only changes the connection timeout value for this one request. It doesn’t affect the CSP gateway connection’s timeout value, which by default is a short 30 seconds (to incentivize writing efficient server-side code).

If fact, to preserve that incentive, we can ensure that the extended timeout is only used in the rare cases we need it by wrapping the client code in conditional code that checks a global, as follows:

    #dim result As %XML.DataSet
    set wc = ##class(SlowSOAPService.WebClient.SlowSOAPServiceSoap).%New()
    if (^reallySlowSvcExpectedTime > 0) {
        set sc = wc.TimeoutSet(^reallySlowSvcExpectedTime)
    }
    set sc = wc.GetSlowService(.result)

The global acts as both a flag (greater than 0? Set the timeout) and the number of seconds to wait. For the issue described at the start of this article, we would notify clients that they should temporarily set a global using an IRIS terminal connected to their instance as follows:

    set ^reallySlowSvcExpectedTime = 600

Once we’re again expecting the service to quickly return a small amount of data, clients can be reset to use the default timeout by setting the global back to 0:

    set ^reallySlowSvcExpectedTime = 0
3 Comments
Discussion (3)2
Log in or sign up to continue
Article
· Dec 8, 2023 2m read
Open Exchange

Business Service to Query Internal IRIS database

#InterSystems IRIS #InterSystems IRIS for Health
Scenario

IRIS has the likes of SQL inbound adapters for use with SQL gateways such as EnsLib.SQL.InboundAdapter to repeatedly query SQL Gateway connections. A scenario appeared as that we wanted to query an Internal database for some data but did not see an out of the box service for this. 

Desired Approach

Have a Generic service that can poll internal SQL to work with downstream components.

How

What was not clear was "How do I send a result set downstream". It was not very clear as a resultset itself is not a peristent class and the object cannot be "Swizzled" an error like so 

 <METHOD DOES NOT EXIST>zNewRequestMessage+4 ^Ens.MessageHeader.1 *%GetSwizzleObject,%sqlcq.SRFT.cls535 -- logged as '-'
number - @''

The solution was using the object 

EnsLib.SQL.Snapshot

This can then be used as a business operation to send a resultset downstream in using the function Import from resultset

set result=##class(EnsLib.SQL.Snapshot).%New()
// Some SQL query here resulting in resultset where rset is the resultset object
set tSC=result.ImportFromResultSet(rset)

You can then send this on to another operation 

set tSC=..SendRequestAsync(..ForwardComponentName,result,0)  Quit:$$$ISERR(tSC)

 

Note in the code uploaded to open exchange available here via github . The example is you can open it up and query it. The below is the classmethod that is used to put into a html. This differs from released example slightly as is taken from a live implementation. 

ClassMethod GetDataTable(pRequest As EnsLib.SQL.Snapshot, html As %String) As %String
{
  //first html obj can be if the styling needs passed
  if $ISOBJECT(html){set html=""}
  //loop get column titles 
  set ColumnIteration=1
  set ColumnCount=pRequest.%ResultColumnCountGet()
  
  set html=html_" <table class=""tg"">"
  set html= html_ " " _"<tr>"
  set meta=pRequest.%GetMetadata() //this is like raw text of the result using it to get the column titles out
  if ColumnCount>0{
    while ColumnIteration<=ColumnCount{
      
      set html= html_ " <th>"_  meta.columns.GetAt(ColumnIteration).colName _" </th>"
      set ColumnIteration=ColumnIteration+1
    }

  }
  set html= html_ " " _"</tr>"
  //not get the data from each row. In html need a <tr> and a td. 
  set coldataiteration=1
  While pRequest.%Next() {
    set html= html_ " <tr>"
    while coldataiteration <=ColumnCount{
      set html= html_ " <td> "_pRequest.%GetData(coldataiteration) _" </td>"
      set coldataiteration=coldataiteration+1
    }
    
    set html= html_ " </tr>"
    set coldataiteration=1
  }
  set html= html_ " " _"</table>"
  $$$TRACE(html)
  return html
}

Sparkei/Internal-SQL-Service: Intersystems service that can be used to query an internal SQL table to send a snapshot downstream (github.com)
 

Discussion (0)1
Log in or sign up to continue
Article
· Dec 4, 2023 10m read

通用RESTful 业务服务和业务操作

#Business Service #Business Operation #Tools #Tips & Tricks #Beginner #Best Practices #HealthShare #InterSystems IRIS #InterSystems IRIS for Health

1. 通用RESTful业务服务和业务操作


InterSystems IRIS 提供了一组通用的RESTful 业务服务和业务操作类，用户无需开发自定义的业务服务和业务操作类，就可以直接向外提供RESTful服务和调用外部的RESTful API。

BS EnsLib.REST.GenericService 通用REST业务服务
BS EnsLib.REST.SAMLGenericService 检查SAML令牌的签名和时间戳的REST业务服务
BO EnsLib.REST.GenericOperation 通用REST业务操作
BO EnsLib.REST.GenericOperationInProc 用于透传模式的通用REST业务操作

 

2. 通用RESTful 消息

 

通用的RESTful 业务服务和业务操作类使用一个通用的RESTful消息类 - EnsLib.REST.GenericMessage，它是EnsLib.HTTP.GenericMessage的子类，二者数据结构都是

HTTPHeaders 记录http头的数组
Stream 记录http体的数据流
Type 数据流类型，例如是字符流还是二进制流。自动赋值，无需设置
Attributes 记录属性的数组
OriginalFilename 无需使用
OutputFolder 无需使用
OutputFilename 无需使用

因此EnsLib.REST.GenericMessage和EnsLib.HTTP.GenericMessage都可以被通用RESTful业务操作和业务服务所使用。

 

3. 通用RESTful 业务操作

使用通用的RESTful业务操作，可以连接到任何第三方的RESTful服务器，调用其RESTful API。

3.1 向production中加入通用RESTful业务操作

增加通用RESTful业务操作，只需要在Production配置页面的操作中添加EnsLib.REST.GenericOperation。

建议加入Production时，给业务操作起一个名字，用于代表具体的业务，例如是连接到LIS的RESTful 服务，可以命名为RESTtoLIS（可以考虑的命名规则 - 接口方式+业务系统）。如果未命名，默认会使用类名作为业务操作名。

3.2 配置通用RESTful业务操作

主要的设置项是以下3个：

1. HTTP服务器：目标RESTful服务器的服务器名或IP地址

2. HTTP端口：目标RESTful服务器提供RESTful API的端口号

3. URL：RESTful API的服务端点

启用该业务操作后，既可以访问外部RESTful API了。

注意，这里URL可以不填写，而由HTTP header动态指定。

3.3 测试通用RESTful业务操作

启用后，加入的通用的RESTful业务操作即可测试了。因为EnsLib.HTTP.GenericMessage的REST消息体是一个流类型的属性，为了测试时方便输入这个数据，我们增加一个业务流程。

1. 创建一个新的业务流程，设置其请求消息为Ens.StringRequest，用于测试时传入REST body数据。并为其上下文增加一个名为DataBody、类型为%Stream.GlobalCharacter（可持久化的字符流类型）的属性：

2. 在业务流程中增加一个代码流程(<code>)，将请求消息的字符串数据写入上下文的DataBody字符流：

Do context.DataBody.Write(request.StringValue)

 注意行首加空格。

 

3. 然后在业务流程中再加入一个调用流程(<call>)，调用上面已经加入production的业务操作，例如RESTtoLIS，并设置请求和响应消息为EnsLib.REST.GenericMessage或EnsLib.HTTP.GenericMessage。

4. 配置RESTtoLIS业务操作的请求消息（Request）

可以直接点击构建请求消息(Request Builder)按钮，使用图形化拖拽建立请求消息：

4.1 将左边上下文context里的DataBody拖拽到callrequest的Stream属性上；

4.2 对callrequest的HTTPHeaders赋值，它是一个元素类型为字符串的数组，代表HTTP请求的头。以下3个HTTP头是必须要填写的：

HTTP头属性说明 下标 值
HTTP方法 "httprequest" 例如"POST"
HTTP消息体的内容类型 "content-type" 例如"application/json"
客户端希望接收的内容类型 "Accept"  例如"*/*"

这3个数组元素赋值，可以通过在添加操作下拉列表中设置(Set)进行赋值。

4.3 （此步可选）如果在3.2中没有配置URL，则可以在这里增加对HTTPHeaders里URL的设置。例如需要动态确定URL，就可以在这里进行配置。如下：

注意，如果这里设置了“URL”，它会覆盖在BO设置中的URL。

4.4 （此步可选）如果有URL参数需要配置，例如/fhir/r4/MedicationRequest?Patient=0a8eebfd-a352-522e-89f0-1d4a13abdebc&_elements=medicationReference，这里需要设置2个URL参数：Patient和_elements，可以用HTTPHeaders的IParams进行设置。

设置方法是：

先确定有多少个参数，将数量放在IParams里，例如2个，所以设置IParams为2；

之后为每个参数设置IParams_i，这里i是参数序号，例如设置IParams_1为“Patient=0a8eebfd-a352-522e-89f0-1d4a13abdebc”；

以此类推。

 

5. 将业务流程加入Production，并测试

确保Production的设置是允许调试。在Production配置页面中选中这个业务流程，在右侧的操作标签页中选择测试按钮，并在弹出的测试消息页面里填入测试用的数据，并点击调用测试服务：

然后可以检查测试的消息处理流程，并确认REST消息体和HTTP消息头被正确地传递到目标REST API

 

 

4. 通用RESTful 业务服务

使用通用的RESTful业务服务，可以向外发布能处理任何RESTful API调用请求的RESTful服务端。

4.1 将通用RESTful业务服务加入Production

在Production配置页面，点击服务后面的加号。弹出的向导页面，服务类选择EnsLib.REST.GenericService；输入服务名，建议写一个能代表组件功能的名字，例如向HIS系统开放的REST服务，可以起名RESTforHIS；选中立即启用。

RESTful通用业务服务可以通过2种方式向外提供RESTful API服务：第一种通过Web服务器向外提供服务，第二种使用IRIS服务器的特定TCP端口向外提供服务。第二种方式不依赖于独立的Web服务器，但推荐使用Web服务器，从而得到更好的性能和安全性。

这里我们使用Web服务器提供REST服务，因此在业务服务的端口配置中，保持空白。在接受消息的目标名称中，选择接收RESTful API请求的业务流程或业务操作，这里我们测试使用一个空的业务流程。点击应用激活这些设置。

4.2 建立一个向外提供RESTful API的Web应用

向外发布RESTful服务，不仅涉及到服务发布的URL，还涉及到安全。我们通过创建一个专用的Web应用来进行管理和控制。

在IRIS系统管理门户>系统管理>安全>应用程序>Web应用程序 中，点击新建Web应用程序按钮，新建一个Web应用程序，并做以下配置：

1. 名称，填写一个计划发布的服务端点，例如/IRISRESTServer。注意前面的/

2. NameSpace，选择Production所在的命名空间

3. 选中启用 REST，并设置分派类为EnsLib.REST.GenericService

4. 根据安全需要，配置安全设置部分。这里方便测试起见，允许的身份验证方法选择了未验证（无需验证）。如果是生产环境，或者您在做性能压力测试，都应该选择密码或Kerberos安全的身份验证方式！

注意，请保证同一个命名空间下，仅有一个分派类为EnsLib.REST.GenericService的REST类型的Web应用。

 

4.3 测试RESTful业务服务

现在就可以测试这个RESTful业务服务了。这个RESTful服务可以响应任何REST API的请求，如何响应则是后续业务流程/业务操作的事。

它的完整的RESTful URL是：[Web服务器地址]:[Web服务器端口]/[Web应用的名称]/[通用REST服务在production中的配置名]/[API名称和参数]，例如我在IRIS本机的私有Apache的52773端口上访问上面创建的REST通用业务服务，调用PlaceLabOrder的API （注意，这里我们并没有实现过PlaceLabOrder这个API，但我们依然可以响应，而不会报404错误），那么完整的REST 调用地址是：

127.0.0.1:52773/IRISRESTServer/RESTforHIS/PlaceLabOrder

打开POSTMAN，用POST方法，发起上面REST API的调用：

 在IRIS里会得到类似这样的消息追踪结果，如果你没有实现过处理REST API请求的业务流程，会得到一个500错，但依然可以查看IRIS产生的EnsLib.HTTP.GenericMessage消息内容：

这个通用RESTful业务服务会把REST请求转换为EnsLib.HTTP.GenericMessage消息，向目标业务操作/业务流程发送。因此，通过解析它的消息内容，就知道REST API请求的全部信息：

1. Stream里是POST的数据

2. HTTPHeaders 的下标"HttpRequest"是HTTP的方法

3. HTTPHeaders 的下标"URL"是完整的API路径，包括了服务端点（在"CSPApplication"下标下）、REST业务服务名称（在"EnsConfigName"下标下）和API

后续业务流程可以通过这些数据对REST API请求进行响应。

4.4 使用业务流程对REST API调用进行路由

有了通用RESTful业务服务生成的EnsLib.HTTP.GenericMessage消息，我们就可以使用消息路由规则或业务流程对REST API请求进行路由。这里我使用业务流程方法对REST API请求进行路由演示。

构建一个新的业务流程，请求消息和响应消息都是EnsLib.REST.GenericMessage或EnsLib.HTTP.GenericMessage，同时为context增加一个名为ReturnMsg的字符串类型的属性，并设置它默认值为："{""Code"":-100,""Msg"":""未实现的API""}"。

在业务流程里增加一个<switch>流程，然后在<switch>下增加2个条件分支，分别为：

名称：下达检验医嘱，条件：判断是否http头的URL为PlaceLabOrder，且http头的HttpRequest为POST：

(request.HTTPHeaders.GetAt("URL")="/IRISRESTServer/RESTforHIS/PlaceLabOrder") && (request.HTTPHeaders.GetAt("HttpRequest")="POST")

名称：查询检验项目，条件：判断是否http头的URL为GetLabItems，且http头的HttpRequest为GET：

(request.HTTPHeaders.GetAt("URL")="/IRISRESTServer/RESTforHIS/GetLabItems") && (request.HTTPHeaders.GetAt("HttpRequest")="GET")

在两个分支里，分别增加<code>, 产生返回的REST消息内容：

 Set context.ReturnMsg="{""Code"":200,""Msg"":""检验医嘱下达成功""}"
 Set context.ReturnMsg="{""Code"":200,""Msg"":""查询检验项目成功""}"

最后在<switch>后增加一个<code>，构建响应消息：

 // 初始化响应消息
 set response = ##class(EnsLib.REST.GenericMessage).%New()
 // 初始化响应消息的流数据
 Set response.Stream = ##class(%Stream.GlobalCharacter).%New()
 // 将REST返回数据写入流
 Do response.Stream.Write(context.ReturnMsg)

编译这个业务流程，并将其加入Production。

之后修改通用RESTful业务服务的设置，将接收消息的目标名称改为这个新建的业务流程。

现在再通过POSTMAN测试一下各种API，并查看返回REST响应：

在真实项目中，根据实际情况，将上面<switch>流程分支的<code>替换为API响应业务流程或业务操作即可。

 

总结：使用通用RESTful业务操作和业务服务，无需创建自定义的RESTful 业务组件类，就可以调用外部RESTful API和向外提供RESTful API服务，降低开发和实施成本，实现低代码开发。

 

后记：关于EnsLib.REST.GenericService对CORS(跨域资源共享)的支持

CORS是一种基于 HTTP 头的机制，通过允许服务器标示除了它自己以外的其它origin(域、协议和端口)等信息，让浏览器可以访问加载这些资源。
所以要让EnsLib.REST.GenericService支持CORS，需要让它的响应消息增加对于CORS支持的HTTP头的信息，这里不详细介绍这些头含义了，大家可以去W3C的网站或者搜索引擎查询具体定义，最简单可以使用以下代码替代上面4.4中的初始化响应消息代码：

  // 设置HTTP响应的头信息
  set tHttpRes=##class(%Net.HttpResponse).%New()
  set tHttpRes.Headers("Access-Control-Allow-Origin")="*"
  set tHttpRes.Headers("Access-Control-Allow-Headers")="*"
  set tHttpRes.Headers("Access-Control-Allow-Methods")="*"
  // 初始化响应消息
  set response = ##class(EnsLib.REST.GenericMessage).%New(,,tHttpRes)

 

关于Cookies：
很多REST API需要事先登陆，获取会话信息并保存到Cookies中，从而作为后续API调用的认证信息。

这种情况下，需要开启Cookies。开启方法是打开REST业务操作组件的配置项“使用Cookie”，见下图。

在开启后，上次API调用返回的消息中的Cookies信息会被保存到业务组件实例中，并在下次API调用时自动加到HTTP头中。

注意，这是针对于同一个REST业务操作组件的。Cookies并不会跨不同的REST业务操作组件共享！


关于返回消息的乱码：

如果你看到返回的REST消息是中文乱码，需要取消选中“阅读原始模式”，见下图。它默认是选中的，意思是不管HTTP头里声明的Charset是什么，它都不会进行转码，因此很适合透传。但如果取消选中该设置，IRIS会基于HTTP头的Charset进行转码，转为IRIS的内码Unicode，从而在消息追踪页面显示正确的中文。

关于HTTPS：

如果IRIS的REST客户端使用HTTPS访问REST服务器端，需要在IRIS实例上配置SSL客户端：

在IRIS系统管理门户>系统管理>安全>SSL/TLS配置中，点击“新建配置”：

输入“配置名称”；

然后“类型”选中“客户端”；

并在“此客户端的凭据” 选择证书文件和密钥文件。如果你手头上没有，可以用openssl生成一对。

保存后，可以测试一下。

然后在BO的配置页面的“Connection Settings”>SSLConfig中选中上一步创建的SSL客户端名称；同时保证HTTPPort里填写正确的端口号，默认HTTPS的端口号是443:

Discussion (0)1
Log in or sign up to continue