For DCIM developers

The IT Advisor Web Service API is a set of web services that provide access to various parts of ITA. The REST API documentation is available at https://<server IP>/api/current/docs/index.html  

If you want to make the ITA web client or Tenant Portal available to your colleagues or customers directly from the Internet, ensure you have a proxy configuration in the DMZ. Note The DMZ setup protecting ITA against direct Internet access is entirely your own responsibility! However, here are some recommendations on what you should set up and how to do this. This is not a complete newbie guide to setting up a proxy server. You should already have a working knowledge about scripting, web proxy and DMZ configuration, or find it easy to acquire this knowledge. #!/bin/sh ############################################################################## # This file provides an example of how to set up Nginx on a systemd based OS like CentOS. ############################################################################## # The address ITA is already listening to. export ITA_ADDRESS=192.168.56.200 # The address Ngnix should be set up to listen on. This should be a domain. www.example.com export NGINX_ADDRESS=www.example.com echo "The ITA server(s) is/are expected to listen on ITA_ADDRESS=$ITA_ADDRESS" echo "The nginx server will be configured to listen on NGINX_ADDRESS=$NGINX_ADDRESS" # Create self-signed cert (to demo https in Nginx) export PATH_TO_PRIVATE_KEY_FILE="/etc/nginx/$NGINX_ADDRESS.key" export PATH_TO_CERTIFICATE_FILE="/etc/nginx/$NGINX_ADDRESS.crt" openssl req -x509 -nodes -sha256 -days 4383 -subj /CN=$NGINX_ADDRESS -newkey rsa:2048 -keyout $PATH_TO_PRIVATE_KEY_FILE -out $PATH_TO_CERTIFICATE_FILE # For production the self-signed cert should be replaced by a signed certificate chown nginx:nginx $PATH_TO_PRIVATE_KEY_FILE chown nginx:nginx $PATH_TO_CERTIFICATE_FILE echo "Created selfsigned private key ($PATH_TO_PRIVATE_KEY_FILE) and certificate ($PATH_TO_CERTIFICATE_FILE) and made nginx owner of these files" # Replace main config file of nginx cat > /etc/nginx/nginx.conf <<EOF # For more information on configuration, see: # * Official English Documentation: http://nginx.org/en/docs/ # * Official Russian Documentation: http://nginx.org/ru/docs/ user nginx; worker_processes auto; error_log /var/log/nginx/error.log; pid /run/nginx.pid; events { worker_connections 1024; } http { log_format main '\$remote_addr - \$remote_user [\$time_local] "\$request" ' '\$status \$body_bytes_sent "\$http_referer" ' '"\$http_user_agent" "\$http_x_forwarded_for"'; access_log /var/log/nginx/access.log main; sendfile on; tcp_nopush on; tcp_nodelay on; keepalive_timeout 65; types_hash_max_size 2048; include /etc/nginx/mime.types; default_type application/octet-stream; # See http://nginx.org/en/docs/ngx_core_module.html#include # for more information. include /etc/nginx/conf.d/*.conf; # Redirect browsers from http to https server { listen 80; rewrite ^(.*) https://$host$1 permanent; } # Set up the proxy to ITA: server { listen 443 ssl; server_name $NGINX_ADDRESS; ssl_certificate $PATH_TO_CERTIFICATE_FILE; ssl_certificate_key $PATH_TO_PRIVATE_KEY_FILE; #First handle requests to the actual application path /web location /web/ { proxy_pass http://$ITA_ADDRESS; } #Handle root requests, and forward to /web (The order matters. The location /web needs to be specified before location /) location / { proxy_pass http://$ITA_ADDRESS/web/; } } } EOF # Make the Nginx user own the config file (nginx user is specified in /etc/nginx/nginx.conf) chown nginx:nginx /etc/nginx/nginx.conf echo "Replaced nginx main config file /etc/nginx/nginx.conf and made nginx owner of the file" # Make sure Nginx starts on boot. # More info on systemd: https://www.digitalocean.com/community/tutorials/how-to-use-systemctl-to-manage-systemd-services-and-units systemctl enable nginx echo "nginx registered as service that starts on boot (not yet started in current session)" # Start nginx in the current session ('systemctl enable nginx' above just makes sure nginx will be started on future boots). systemctl start nginx echo "Started nginx in the current session, note interesting paths:" echo "- for errors see /var/log/nginx/error.log" echo "- for config see /etc/nginx/nginx.conf" echo "" echo "Serving the Tenant Portal at: $NGINX_ADDRESS" # Other notes: # - keep an eye on security warnings and patch OS and Nginx as needed # - proactively keep an eye on suspicious / unusual behavior # - setup logging # systemctl start|stop|restart|reload|reload-or-restart|status|is-active|is-enabled|is-failed nginx # # if service does not support reload (of config), then use reload-or-restart # # List current services: # systemctl list-units # # Default global nginx config file at: /etc/nginx/nginx.conf # Defines error log locations, e.g.: # - /var/log/nginx/error.log # - /var/log/nginx/access.log # # PID is written to: /var/run/nginx.pid # List nginx processes: ps -ax | grep nginx  

ITA uses the standard web services to query Data Center Expert for device and sensor related data. Device Information To get device information, this information from the DCE web interface /integration/services/ISXCentralDeviceService_v2_0?wsdl is used: <xsd:complexType name="ISXCDevice"> <xsd:sequence> <xsd:element name="ISXCNamedElement" nillable="true" type="ns2:ISXCNamedElement"/> <xsd:element name="ISXCCommState" nillable="true" type="ns2:ISXCCommState"/> <xsd:element name="ISXCDeviceType" nillable="true" type="ns2:ISXCDeviceType"/> <xsd:element minOccurs="0" name="hostName" nillable="true" type="xsd:string"/> <xsd:element minOccurs="0" name="ipAddress" nillable="true" type="xsd:string"/> <xsd:element name="location" nillable="true" type="xsd:string"/> <xsd:element minOccurs="0" name="modelName" nillable="true" type="xsd:string"/> <xsd:element minOccurs="0" name="modelNumber" nillable="true" type="xsd:string"/> <xsd:element name="parentID" nillable="true" type="xsd:string"/> <xsd:element minOccurs="0" name="serialNumber" nillable="true" type="xsd:string"/> <xsd:element name="ISXCDeviceState" nillable="true" type="ns2:ISXCDeviceState"/> <xsd:element minOccurs="0" name="supplemental" nillable="true" type="xsd:string"/> </xsd:sequence> <xsd:attribute name="isPrivate" type="xsd:boolean"/> </xsd:complexType> Note The supplemental string is mandatory to understand the nature of the device. For example, for power related devices, phase and bank information is present in the supplemental string used in ITA to create an object of the device. Example of  PDU with 1 phase and 2 banks: <ns2:supplemental>InputPhaseCount="1";OutputPhaseCount="1";BankCount="2"</ns2:supplemental>   Sensor Information A number of sensors are also used from the DCE web service interface /integration/services/ISXCentralSensorService_v2_0?wsdl To create an object to be used for the sensors, use: Note Index is being used to identify which module and phase are reporting data. That means index must be unique across sensorType on a given device   It is NOT allowed to have e.g. 2 sensors of the same sensorType reporting same index. For example a single phase rack PDU with 2 banks and reporting phase information as well. Same sensorType having same index: This is NOT allowed <ns2:ISXCElementType>SENSOR</ns2:ISXCElementType> <ns2:id>B717125_nbSNMPEncEC23C4AA_RPDU_OUTPUT_POWER_BANK_1</ns2:id> <ns2:index>1</ns2:index> <ns2:ISXCSensorType>OUTPUT_POWER_WATTS</ns2:ISXCSensorType> <ns2:ISXCElementType>SENSOR</ns2:ISXCElementType> <ns2:id>B717125_nbSNMPEncEC23C4AA_RPDU_PHASE_OUTPUT_POWER_1</ns2:id> <ns2:index>1</ns2:index> <ns2:ISXCSensorType>OUTPUT_POWER_WATTS</ns2:ISXCSensorType> To get the above example right, the phase output power should be reported as OUTPUT_POWER_TOTAL_WATTS (which does not use index). Single phase devices with no banks should only use the OUTPUT_POWER_TOTAL_WATTS sensorType. From the ISXCSensorType, a subset of the sensors are mapped in ITA for temperature, humidity, and power. Temperature Sensors: EXTERNAL_TEMPERATURE SUPPLY_AIR_TEMPERATURE RETURN_AIR_TEMPERATURE INTEGRATED_TEMPERATURE RACK_INLET_TEMPERATURE UNIT_TEMPERATURE Humidity Sensors: EXTERNAL_HUMIDITY SUPPLY_AIR_HUMIDITY RETURN_AIR_HUMIDITY INTEGRATED_HUMIDITY UNIT_HUMIDITY Power Sensors: OUTPUT_POWER_WATTS OUTPUT_POWER_TOTAL_WATTS MODULE_OUTPUT_POWER or MODULE_BREAKER_POWER Amp Sensors: MODULE_BREAKER_CURRENT OUTPUT_CURRENT OUTPUT_CURRENT_TOTAL INPUT_CURRENT   The SensorType is ignored when using sensor mapping functionality at PDU level. Tip Power sensors used for Modular PDU / Branch Circuit Monitoring For a modular PDU/Branch Circuit Monitoring, the MODULE_OUTPUT_POWER or MODULE_BREAKER_POWER are the sensors used to get power data from the device.   An example of a modular PDU with 3 phases and 24 breaker modules: At device level, the "supplemental" string is used to specify number of phases and breaker modules.   <ns2:supplemental>InputPhaseCount="3";OutputPhaseCount="3";BankCount="24"</ns2:supplemental> At sensor level, the sensorType is used to specify a modular PDU reporting data and the index is used to identify the phase reporting on a module. In this example breaker module 5, phase 3 (index 5,3): <ns2:ISXCSensorType>MODULE_OUTPUT_POWER</ns2:ISXCSensorType> <ns2:index>b,p</ns2:index> - e.g. <ns2:index>5,3</ns2:index> Data Collection The data collected from DCE via the power sensors is Peak and Average data. Peak and Average power data is queried for an interval of one day, 1 time/day. Additionally, peak power data is queried every 5 minutes since last time queried. We store the data and calculate Peak and Average values based on a setting in the ITA server (10, 20, 30 days).   Summary The expected values used to specify and map the device in ITA: ISXCDevice - Supplemental ISXCSensor PhaseCount BankCount Index SensorType Device example 1 1 Ignored OUTPUT_POWER_TOTAL_WATTS rack PDU 1 >1 1 digit = Bank number OUTPUT_POWER_WATTS rack PDU with banks 1 - Ignored OUTPUT_POWER_TOTAL_WATTS   3 1 1 digit = Phase number OUTPUT_POWER_WATTS UPS or (RM)PDU 3 >1 2 digit = Module, Phase MODULE_OUTPUT_POWER Modular PDU 3 - 1 digit = Phase number OUTPUT_POWER_WATTS     Note Supplemental is mandatory and must include phase information PhaseCount references InputPhaseCount and OutputPhaseCount which is expected to be the same number. DCE exposes information through various web services. For device information, ITA uses: getAllDeviceGroups getDevicesForGroupID   For sensor information and data, ITA uses:  getSensorsByType getMultipleAverageSensorData getMultiplePeakSensorData Verifying DDFs with Soap-UI The walkthrough below is done with SoapUI 5.4.0. You can download the latest version here: https://www.soapui.org/ When setting up a new project, chose the SOAP project type. Screenshot1_360006754317.png The initial WSDL link should be http://X.X.X.X/integration/services/ISXCentralDeviceService_v2_0?wsdl for the device endpoint. http://X.X.X.X/integration/services/ISXCentralSensorService_v2_0?wsdl for the sensor endpoint. Where X.X.X.X is ip address for the DCE server. Screenshot2_360006754317.png When prompted for the username and password, provide those used for logging into the DCE server. Running a request against the DCE server When running a request against the endpoint, first choose the endpoint in the list, and fold out so you can see the sample request. Screenshot3_360006754317.png Before running the request, you need to setup authentication: Chose 'Basic' Enter in the username and password for the DCE server Screenshot4_360006754317.png Then press play to run the request. Dependent on the request it might be necessary to fill in a number of parameters. When you have identified the correct device use the sensor end point to ensure that sensors with the correct type are available. Running requests to verify sensors with the correct type are available Getting the sensors for a specific device. Several of the end point are of interest, this is just an example on one why to do the verification. Given an ID for a device, all the sensors for the device can be gathered with the getSensorsForDevice request. Screenshot5_360006754317.png Fill in the ID for the device Screenshot6_360006754317.png Check that sensors with the types mentioned in the first part of this document are present. One example for the OUTPUT_POWER_WATTS sensor type is shown below. Screenshot7_360006754317.png  

Terminology ITA: EcoStruxure IT Advisor DCE: Data Center Expert Device: A physical piece of equipment that we monitor, for example, power, temperature or humidity on. Sensor: A measuring entity for a device, for example current on phase L1, return air humidity. Measurement: A specific measurement for a sensor, has a timestamp. Sensor Mapping (ITA): For power distribution devices there is a feature in ITA where you can take a specific sensor and say which circuit that sensor monitors. This is called sensor mapping and is not the same as what happens in the DDF files. Typical steps to verify that the DDF is correct 1. Verify if the device shows up in EcoStruxure IT Go to Planning > Device Association > Unassociated Devices. If the devices do not appear in IT Advisor, check the following: - Verify that the external system configuration points to the correct Data Center Expert server. - Verify that the device is in Data Center Expert, and verify that you can see the devices using the DCE web services. - The device types that ITA does not understand are shown with type 'Unknown'. See DCE Sensor Mapping to ITA 2. Verify that temperature and humidity sensors are shown in ITA The sensors are listed underneath each devices in the Unassociated Devices view. It is not necessary to associate the device to see the temperature and humidity sensors. ITA_Temperature_sensor_360006791257.png Only temperature and humidity sensors that have a sensor type in the list below are recognized by ITA. Temperature sensor types: EXTERNAL_TEMPERATURE SUPPLY_AIR_TEMPERATURE RETURN_AIR_TEMPERATURE INTEGRATED_TEMPERATURE RACK_INLET_TEMPERATURE UNIT_TEMPERATURE Humidity sensor types: EXTERNAL_HUMIDITY SUPPLY_AIR_HUMIDITY RETURN_AIR_HUMIDITY INTEGRATED_HUMIDITY UNIT_HUMIDITY Note Normally when you associate a device from the unassociated devices view, the device disappears from the list. The devices however remain in the list if it has related temperature or humidity sensors as they are shown as children in the tree structure. Note Temperature and humidity sensors are only shown when the 'Retrieve sensors' checkbox on the second page in the configuration wizard is checked. ITA_Temperature_sensor_2_360006791257.png 3. Verify that power and amps measurements are shown in ITA On the device of interest, right-click and choose 'Properties'. In the properties dialogue, unfold the External Systems entry and select the Device subpage. ITA_Device_properties_360006791257.png The power and amps measurements should show here. It is not necessary to associate the device to see if the power and amps measurements are recognized. ITA_Measurement_property_page_360006791257.png For the measurements to show a number of requirements must be satisfied: The DDF file must list the InputPhaseCount and OutputPhaseCount, and they are expected to be the same. Furthermore the BankCount is also needed in some cases. The following power sensors are recognised by ITA:  OUTPUT_POWER_WATTS OUTPUT_POWER_TOTAL_WATTS MODULE_OUTPUT_POWER MODULE_BREAKER_POWER The following amp sensors are recognized by ITA:  MODULE_BREAKER_CURRENT OUTPUT_CURRENT OUTPUT_CURRENT_TOTAL INPUT_CURRENT Make sure that the DDF adheres to the following table ISXCDevice - Supplemental ISXCSensor PhaseCount BankCount Index SensorType Device example 1 1 Ignored OUTPUT_POWER_TOTAL_WATTS rack PDU 1 >1 1 digit = Bank number OUTPUT_POWER_WATTS rack PDU with banks 1 - Ignored OUTPUT_POWER_TOTAL_WATTS   3 1 1 digit = Bank number OUTPUT_POWER_WATTS UPS or (RM)PDU 3 >1 2 digit = Module, Phase MODULE_OUTPUT_POWER Modular PDU 3 - 1 digit = Bank number OUTPUT_POWER_WATTS     Example list of power sensors and how ITA understands them Single phase rack PDU or phase-phase rack PDU, with one bank (PhaseCount: 1, BankCount: 1): Index SensorType Interpretation by ITA Ignored OUTPUT_POWER_TOTAL_WATTS The total power measurement for the rack pdu Single phase rack PDU or phase-phase rack PDU, with three banks (PhaseCount: 1, BankCount: 3): Index SensorType Interpretation by ITA 1 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 1 2 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 2 3 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 3 Ignored OUTPUT_POWER_TOTAL_WATTS Total measurement for the rack pdu Three phase rack PDU, with one bank (PhaseCount: 3, BankCount: 1): Index SensorType Interpretation by ITA 1 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 1 2 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 2 3 OUTPUT_POWER_WATTS The power measurement for the rack pdu's bank 3  Modular PDU (PhaseCount: 3, BankCount: 3): Index SensorType Interpretation by ITA 1.1 MODULE_OUTPUT_POWER The power measurement for module 1, phase 1 1.2 MODULE_OUTPUT_POWER The power measurement for module 1, phase 2 1.3 MODULE_OUTPUT_POWER The power measurement for module 1, phase 3 2.1 MODULE_OUTPUT_POWER The power measurement for module 2, phase 1 2.2 MODULE_OUTPUT_POWER The power measurement for module 2, phase 2 2.3 MODULE_OUTPUT_POWER The power measurement for module 2, phase 3  

See the Web Services API section for Data Center Expert. The Data Center Expert web services API is available for download on apc.com: http://www.apc.com/products/resource/include/techspec_index.cfm?base_sku=SFWEBSVC