Day 8 - SOAP Web Services.pdf

SuiteCloud: Integrations SOAP Web Services Team Panthers 2024 Enable Features Enable SuiteCloud Setup Company...

SuiteCloud: Integrations SOAP Web Services Team Panthers 2024 Enable Features Enable SuiteCloud Setup Company Features tab 3 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted What is a Web Service? Customers may want to integrate their other software with NetSuite to synchronize their data and allow smooth processing between applications. For example, a customer may also have a Point-Of-Sale System, an E-commerce website and another external Web Service website that they want to synchronize with NetSuite. They can use Web Services to achieve this. In NetSuite, there are two types of Web Services: SOAP Web Services REST Web Services 4 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services SOAP Web Services allows other applications to communicate with NetSuite using the Simple Object Access Protocol or SOAP. SOAP Web Services 5 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Parts of a SOAP Request Envelope Envelope (container) Container for the SOAP Request. Usually contains the WSDL version. (e.g., 2021.1) Header Header (credentials) Contains credentials to determine if the request is from a secure source. (e.g., Token Based Authentication credentials) Body Body (command) Contains the command or request that the sender is asking from NetSuite. (e.g., create a new Task record) 6 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Parts of a SOAP Request (Sample) Envelope (container) Header (credentials) Body (command) 7 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted NetSuite WSDL and Versioning (SA: 10822) WSDL or Web Services Description Language is used to describe how to write web services requests in SOAP. NetSuite uses its own WSDL, with different versions coming out in each NetSuite release. The naming convention for NetSuite versions and WSDL versions are the same. For example, for 2022.1, there is an accompanying 2022_1 version of the WSDL. The URL is for this WSDL is: https://webservices.netsuite.com/wsdl/v2022_1_0/netsuite.wsdl Be aware that when your NetSuite account is upgraded, you do not have to upgrade your WSDL to the supporting NetSuite version. For example, you may still use 2021.1 WSDL even if your account has upgraded to 2022.1. 8 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Support for Existing WSDL Versions (SA: 10817) At any time, the six latest endpoints are supported. If you use an older version, NetSuite recommends that you upgrade to the latest WSDL version. NetSuite also makes the eight additional endpoint versions from the previous four years available without support. Endpoints that are 15 and more versions older will be retired. After your NetSuite implementation is upgraded to a newer version, retired endpoints are not available anymore. If you do not upgrade to a newer endpoint when your WSDL is retired, your integrations will cease to work because the endpoint for that version will not be available. 9 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Testing SOAP Web Services 10 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Testing SOAP Web Services To test SOAP Web Services internally, we need the following: Username and Password for accessing your test account Account ID for your test account Check the URL, make sure to include and capitalize TSTDRV. (e.g., TSTDRV123456) Integration Record SOAP UI Bundle (ID: 500259) For this demo, we will be using User Credentials as the authentication method. 11 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Integration Record Manage Setup Integrations New Integrations An Integration record enhances Field Name Description management and monitoring of SOAP web services requests sent to Application ID Represents your integration record. your NetSuite account. If you want to block requests from this State This tracks which specific application application. each request originates. Concurrency Limit Number of concurrent requests allowed for this application. TBA Allows creation of tokens through UI Authenticate using user credentials User Credentials (username/password) 12 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: Creating an Integration Record 13 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP UI Bundle (ID: 500259) Important: This bundle is for Internal use only! Make sure to install before moving forward. This bundle is used internally to simulate sending and receiving SOAP requests/responses. In practice, SOAP requests are created by third-party applications. In Support, we assess only the SOAP requests and responses being sent or received and not the third-party application itself. This bundle will help test and recreate SOAP responses for troubleshooting customer concerns. 14 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: Sending an add Request to create a Task via SOAP WS 15 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: Error sending an add Request 16 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Behavior When we execute any action via That means that if we create a Task SOAP WS, its behavior directly the same way but via SOAP WS, then mirror when that action is done in we would also get the same error. the UI. For example, say we have a custom field in the Task record marked as mandatory. When we attempt to create a Task in the UI, then fail to set that custom field we get an error: That’s why one of the best ways to troubleshoot web services errors is to replicate the operation in the UI. 17 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP Request/Response XML 18 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Request/Response XML SOAP requests/responses are written in XML format. The SOAP WS UI Suitelet merely helps us build this XML in an intuitive way. Outside of Support, these XML files are generated by integration software created by third party developers. As part of Support, we ONLY investigate requests received and responses sent by NetSuite. Troubleshooting third party integration software is out of scope of support. It is an important part of troubleshooting SOAP Web Services to be able to read SOAP requests and responses in XML format. That way, you can replicate the behavior in the UI and assess the cause of issues in SOAP WS. 19 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Schema Browser SOAP Schema Browser Provides a summary of all records, sublists, and other objects available in SOAP web services. Information about each object is displayed as a series of tables, both for ease of browsing and to provide additional details compared with what is available in the WSDL. Field IDs used in SuiteScript are not exactly the same ones used in SOAP Web Services. You may use this reference to know which ones to use in SOAP WS. 20 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Authentication Methods 21 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Authentication for SOAP Web Services Each request needs to be authenticated by NetSuite to know if it is sent by an authorized source. Here are the available methods of authentication: User Credentials Token-Based Credentials Outbound Single Sign-on (SuiteSignOn)* * this isn’t covered in this module. It is important to note that only 1 authentication method in each SOAP message can be used. Mixing different authentication types in a single SOAP message returns a SOAP fault. 22 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Authentication via User Credentials Let’s review the elements necessary to use User Credentials for authentication. If an endpoint of 2020.2 SOAP or higher is used, authentication through request-level credentials is not supported. Passport Object Contains the user’s login email, password and account ID. Role can also be configured. ApplicationInfo Object Contains the Application ID from the Integration record. 23 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Authentication via TBA Token-Based Authentication or TBA is now the recommended way for integrations to authenticate with NetSuite. To start using TBA, we need to set up a few things: Enable Feature Setup > Company > Enable Features > SuiteCloud tab > Manage Authentication section > Token-Based Authentication Access Token Integration Record Token-Based Authentication must be enabled 24 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: Setting up TBA 25 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Resetting TBA credentials Consumer Key/Consumer Secret Token ID/Token Secret If lost, a new Consumer Key and If lost, a new Token ID and Token Secret Consumer Secret can be regenerated by can be regenerated by creating a new editing the relevant Integration record Token. and clicking on Reset Credentials Once a new token is created, the old token MUST be revoked to avoid any security risk. To revoke an old token, edit the respective token record and click Revoke. This will render the old Consumer Key and Secret invalid, so make sure to update old integrations using these values accordingly. 26 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: Authentication via TBA using SOAP WS UI 27 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Authentication via TBA: TokenPassport Let’s break down the resulting TokenPassport object. Account Timestamp The target account’s ID. Current timestamp in Unix format. Consumer Key Signature Generated when enabling TBA in an Integration A hashed value created using all other values in record. the TokenPassport, plus the token secret and Token consumer secret. Generated using HMAC- Generated when creating an Access Token SHA256 encryption. (Token ID). Nonce * See article TokenPassport Complex Type for A randomly generated alphanumeric string of more detailed descriptions of these elements 6–64 characters. Cannot be reused per request. 28 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Operations 29 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Standard Operations Examples Add Add one record into the system. The system returns the created record’s Internal ID when completed. Get Query the system for one record using its internal/external ID and its type. Search Search for a set of records based on specific search criteria. This operation supports pagination. Update Update one existing record in the system identified by its internal/external ID and its type. Upsert Add a new record or update an existing record in a single operation. If a record matches the external ID and type, it is updated. If no records match, a new record is created. 30 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP Operation - get 31 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP Operation – search (Advanced) 32 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP Operation – update 33 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP Operation – upsert 34 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services List Operations Compared to standard operations, List Operations: a list operations lets you use addList standard operations multiple updateList times in one request. upsertList A list operation can also handle multiple record types in one deleteList request (e.g., adding 3 customers, getList 4 opportunities, and 1 contact) initializeList They work the same as their standard operations counterpart, just multiple times in one request. 35 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP WS List Operations 36 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Warnings, Errors, and Faults Warnings Errors Faults Informational Exceptions returned on a A fundamental exception notifications requiring an record-by-record basis type that results in the action within the UI but due to invalid or entire request not being requiring no response incomplete data. The processed. from a Web service call. service is processed as All operations in the Data may or may not be requested, however, only same request will not be processed depending on those records without processed. preference settings. errors are updated. Does not affect other operations sent in the same request. 37 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Asynchronous Operations Asynchronous equivalents are available for several synchronous operations. This is an alternative if going beyond the record limitations of using the synchronous operation is necessary. When sent, the response contains a Job ID. A checkAsyncStatus request must be sent to check if the execution is complete. When completed, the result can be retrieved using getAsyncResult. Job IDs are valid for 30 days. Afterwards the request is no longer available. 38 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Record Limitation As shown in these tables, each asynchronous operation doubles the maximum record count of its synchronous counterpart. 39 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Video: SOAP WS Asynchronous Operations 40 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted Configuration & Troubleshooting 41 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Preferences SOAP Web Services Setup Integration Preferences These affects how the system handles SOAP WS requests. Each preference can be explained by checking their field level help or by looking under the SOAP Web Services Preferences article in Help Center or SuiteAnswers. 42 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Usage Log SOAP Web Services Setup Integration Usage Log This is a log of all synchronous SOAP WS requests that were received by the system. It details which integration sent the request, the SOAP action taken and its status. The Request and Response XML files can also be downloaded from this page. 43 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted SOAP Web Services Process Status SOAP Web Services Setup Integration Process Status This logs all asynchronous SOAP WS requests that were received by the system. It details which integration sent the request, the SOAP action taken and its status. 44 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted TBA and the Login Audit Trail You can use the Login Audit Trail to track TBA tokens and users. To track tokens and users: 1. Go to Setup > Users/Roles > User Management > View Login Audit Trail. 2. Check the Use Advanced Search box. 3. Click the Results subtab. 4. Add the following fields: Detail, Token-based Access Token Name, and Token-based Application Name. 5. Click Submit. 6. The Detail column displays error messages for any token-based authentication logins with a status of Failure. Sample TBA Errors 45 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted ACTIVITY 1. Sales Order Advanced Search: Show the ff fields Internal ID Amount Customer's Email 2. Search all Employee Records with no email 3. Do the ff in one request Add a Sales Order Add a Purchase Order Add an Employee Update a Custom Field on a Customer Record 46 Copyright © 2024, Oracle and/or its affiliates | Confidential: Internal/Restricted/Highly Restricted