PSOPPC Web Service Users Manual. February 2017, Version 1.1

Transcription

1 PSOPPC Web Service Users Manual February 2017, Version 1.1

2 DOCUMENT CHANGE HISTORY Version Number Date Page(s) Affected Description 1.0 June 2014 Initial version 1.1 February 2017 Content updates PSOPPC Web Service Users Manual iii

3 Table of Contents: 1. Introduction Objectives Intended Audience Program Overview PSOPPC Web Service Overview Obtaining a User Account for Accessing PSOPPC Web Service URLs of Web Service Definition Language (WSDL) Patient Safety Event Data Submission SOAP API Batch Submission Status Function File Submission Status Functions Building a Java Web Service Client Using Event Data Submission API in Eclipse IDE Generate Java Based Client Stubs in Eclipse Configuration Changes in the Java Web Service Client Project Sample Java Code Snippet to Call Web Service Method: Sample Outputs Batch Submission Status Sample XML Output File Submission Status Sample XML Output PSOPPC Web Service Users Manual iii

4 1. Introduction 1.1 Objectives The primary objective of this document is to provide users technical information for using a Web Service to verify data submission status from the Patient Safety Organization Privacy Protection Center (PSOPPC) web site. 1.2 Intended Audience The intended audience for this manual are software developers, technical architects and leads involved in submitting formatted data to the Patient Safety Organization Privacy Protection Center (PSOPPC). 1.3 Program Overview The Agency for Healthcare Research and Quality (AHRQ) coordinates the development of Common Formats for patient safety event reporting and analysis. This activity is authorized by the Patient Safety and Quality Improvement Act of 2005 (Patient Safety Act) and the Patient Safety and Quality Improvement Final Rule (Patient Safety Rule). A major goal of the legislation is to allow aggregation of data to identify and address underlying causal factors affecting patient quality and safety. 1.4 PSOPPC Web Service Overview Upon submission of patient safety event (PSE) data to the PSOPPC, users are encouraged to review the status of their data submissions. Traditionally, a user manually generates a Patient Safety Event Submission Management Summary or Detail Report to review the status of data submissions. To generate this report, the Level 3 account user is required to log onto the PSOPPC Web site, enter the appropriate parameters, and run the summary or detail reports. The PSOPPC has developed a second tool to verify data submission status: a Web service option. The Web service allows users to query the submission status of PSE data submissions. The user can call the service to retrieve batch level processing status, and the file submission status. The batch level processing status includes details, such as, the PSOPPC system generated batch ID, submitted file name, submission type, number of files in the batch, PSO ID and name, processing status, submission source, etc. The file submission status provides the file status after processing is complete (i.e., Accepted or Rejected), the error message(s) for any rejected file(s), the user who performed the submission, etc. This Web service offers three different options for users when calling to retrieve the file submission status; by batch IDs, by file name ending with.xml, or by date range. PSOPPC Web Service Users Manual 1

5 2. Obtaining a User Account for Accessing PSOPPC Web Service A second user name and password will be required for accessing the Web service to retrieve the PSE data submission status. Please contact PSOPPC Help Desk at support@psoppc.org or at (866) to setup a PSOPPC Web Service User Account. 3. URLs of Web Service Definition Language (WSDL) The following URL is to be used by the end user to invoke the PSOPPC PSE data submission status web service. PSOPPC Web Service Users Manual 2

6 4. Patient Safety Event Data Submission SOAP API 4.1 Batch Submission Status Function SOAP Function Description Input Output getsubmissionbybatchfilename Example using the function: getsubmissionbybatchfilename ( Infection1.zip ) Returns a collection of batch level processing details by the file name query. batchfilename data submission file name, the extension can be.zip or.xml only; application will perform a case insensitive exact match search. submissiontype must be test or production message If the web service call fails an error message is displayed, otherwise success is displayed numofrecords number of batches found within the given parameters Batch ID PSE Batch ID created when submission reaches import processor, Alternate Data Submission PSE Batch ID created when alternate data is successfully processed status RECEIVED (submission received and still processing), REJECTED (failed to process), COMPLETED (data successfully processed), DELETED (Test data deleted) submissionsource submissions received via Web site, SFTP (CDA XML files), SFTP (Alternate Data Submission files) *Other output information includes organization information, submission date, and error messages if the status is Rejected.* 4.2 File Submission Status Functions SOAP Function Description Input Output getfilesubmissionbybatchids Examples using the function: getfilesubmissionbybatchids({1567}) getfilesubmissionbybatchids({1567,1 568,1573} Returns a collection of the file submission status by the batch IDs. BatchIds list of batch IDs separated by commas, grouped by brackets containserror true or false to indicate if the web service call contains any error message success or error messages associated with web service call such as Invalid batch ID infolist One or more file submission status including batch ID, file name, file status, submission type, submission date, username, error message(s) associated with the event data submission PSOPPC Web Service Users Manual 3

7 getfilesubmissionbyfilename Example using the function: getfilesubmissionbyfilename( blood -event-data.xml ) Returns a collection of the file submission status by the file name queried filename XML file name containserror true or false to indicate if the web service call contains any error message success or error messages associated with web service call such as Invalid file name infolist One or more file submission status including batch ID, file name, file status, submission type, submission date, username, error message(s) associated with the event data submission getfilesubmissionbydate Example using the function: getfilesubmissionbydate( 01/01/20 13, 01/01/2014 ) Returns a collection of the file submission status within the date range indicated by the start date and the end date startdate the start date in the format of MM/DD/YYYY enddate the end date in the format of MM/DD/YYYY containserror true or false to indicate if the web service call contains any error message success or error messages associated with web service call such as Invalid date infolist One or more file submission status including batch ID, file name, file status, submission type, submission date, username, error message(s) associated with the event data submission PSOPPC Web Service Users Manual 4

8 5. Building a Java Web Service Client Using Event Data Submission API in Eclipse IDE 5.1 Generate Java Based Client Stubs in Eclipse 1. Create a new Dynamic Web Project. Click File -> New -> Dynamic Web Project. 2. The new Dynamic Web Project window is displayed. Enter the project name as EventDataSubmissionStatusClient and then click Finish. PSOPPC Web Service Users Manual 5

9 3. Create a new Web Service Client by right clicking the EventDataSubmissionStatusClient folder. Select New -> Other. 4. The Select a wizard window pops up. Select Web Services-> Web Service Client and click Next. PSOPPC Web Service Users Manual 6

10 5. Enter Service definition as and then click Finish. 6. The web service client will be automatically generated. 5.2 Configuration Changes in the Java Web Service Client Project Set up username, password and web service endpoint URI in a configuration file. Here we will use configuration.properties: #Respective FTP user name username.property = test #Respective FTP user password password.property = password #WSDL address for the web service endpoint.address.property = PSOPPC Web Service Users Manual 7

11 5.3 Sample Java Code Snippet to Call Web Service Method: #load a properties file Properties properties = new Properties(); try { properties.load(new FileInputStream("configuration.properties")); } catch (IOException ex) { ex.printstacktrace(); } eventdatasubmissionstatusserviceportbindingstub._setproperty(javax.xml.rpc. Stub.USERNAME_PROPERTY, properties.getproperty("username.property")); eventdatasubmissionstatusserviceportbindingstub._setproperty(javax.xml.rpc. Stub.PASSWORD_PROPERTY, properties.getproperty("password.property")); eventdatasubmissionstatusserviceportbindingstub._setproperty(javax.xml.rpc. Stub.ENDPOINT_ADDRESS_PROPERTY, properties.getproperty("endpoint.address.property")); #call web service method getfilesubmissionbybatchids long batchids[] = {1944,1945}; FileSubmissionList filesubmissionstatus = filesubmissionstatuswebservice.getfilesubmissionbybatchids(batchids); PSOPPC Web Service Users Manual 8

12 6. Sample Outputs 6.1 Batch Submission Status Sample XML Output The following output example is using the getsubmissionbybatchfilename method: <S:Envelope xmlns:s=" <S:Body> <ns2:getsubmissionbybatchfilenameresponse xmlns:ns2=" <return> <inputbatchfilename>infection1.zip</inputbatchfilename> <inputsubmissiontype>test</inputsubmissiontype> <message>success</message> <numofrecords>1</numofrecords> <recordlist> <psebatchid>4763</psebatchid> <psoid>p0000</psoid> <psoname>test PSO</psoName> <status>completed</status> <submissionsource>website</submissionsource> <submissiontype>test</submissiontype> <submitdate> t09:14: :00</submitdate> </recordlist> <requestorgid>p0000</requestorgid> <requestorgname>test PSO</requestOrgName> <servicecallsuccess>true</servicecallsuccess> </return> </ns2:getsubmissionbybatchfilenameresponse> </S:Body> </S:Envelope> PSOPPC Web Service Users Manual 9

13 6.2 File Submission Status Sample XML Output The following output example is using the getfilesubmissionbybatchids method: <S:Envelope xmlns:s=" <S:Body> <ns2:getfilesubmissionbybatchidsresponse xmlns:ns2=" <return> <containserror>false</containserror> <infolist> <batchid>1944</batchid> <filename>venous Thromboembolism 1.2.xml</fileName> <filestatus>accepted: Full Data Set</fileStatus> <submitdate> t11:40: :00</submitdate> <testcasestatus>yes</testcasestatus> </infolist> <infolist> <batchid>1945</batchid> <filename>venous Thromboembolism 1.2.xml</fileName> <filestatus>deleted</filestatus> <submitdate> t11:20: :00</submitdate> <testcasestatus>yes</testcasestatus> </infolist> <message>success</message> </return> </ns2:getfilesubmissionbybatchidsresponse> </S:Body> </S:Envelope> PSOPPC Web Service Users Manual 10