the presentation describes how to connect the issue tracker software atlassian jira with apex, using REST Webservices.
The slides were presented in Rotterdam at the APEX World conference in the netherlands.
2. Facts & Figures
Independent Technology House
with Cross-Industry Expertise
Headquarter
Ratingen
(North Rhine – Westphalia)
240
Employees
Founded
1994
Branches
Dortmund, Cologne,
Frankfurt
Top Company
for Trainees &
Students
Privately-
Owned
Corporation
Oracle
Platinum
Partner
24 Mio. Euro
Revenue
2
3. about me
Oliver Lemm
since february 2007 working for MT AG in Ratingen
Junior Consultant > Consultant > Senior Consultant
> Competence Center Leader APEX & Service Center Leader APEX
Diploma applied computer science at the university of Duisburg-Essen
Projectleader, IT-Architect and Developer
working with Oracle Databases and Oracle Application Express since 2007
Blog http://oliverlemm.blogspot.de
Twitter https://twitter.com/OliverLemm
3
4. APEX Connect
26th – 28th April 2016 in Berlin
Get your early-bird ticket now!
APEX.DOAG.ORG#APEXCONN16
6. Motivation
„Working with one tool to handle the developing process,
controlling and all other processes in one project“
„Calculating key figures based on Jira values which are not delivered by Jira itself.“
„Using integrated Jira Plugins and adding additional
functionality by using APEX as known technology“
6
requirements
7. Jira
https://www.atlassian.com/JIRA
Issue tracking and code integration
Supporting Dashboards & Plugins
perfect integration from Confluence (wiki)
and Subversion (versioning)
supporting complex workflows
Issue import from Bugzilla, Mantis, GitHub, …
Supporting von REST-Webservices
7
10. Jira
supporting a huge number of attributes
time tracking (estimated, time spent, remaining)
Components (can be used for APEX pages and database objects)
versions
fields and screens adjustable per project
external issue numbers, date of commision, date of payment
Supporting own workflows
Describing a whole process, usable for non developing processes
Every step can be defined by user rights or issue dependencies
Using „JIRA Timesheet Reports and Gadgets Plugin“
10
Integrated features
11. Jira
key figures not in desired aggregation
time per year/month
no further support for SOAP Webservices in Jira
SOAP Interface doesn‘t return all values
Using Jira-Plugins
Listed Plugins not fullfilling all requiremends
Developing own Jira-Plugins is complex and time consuming
11
lack of features
12. Jira
API documentation for Jira REST-Webservices
https://docs.atlassian.com/jira/REST/latest/
URL structure
http://host:port/context/rest/api-name/api-version/resource-name
Using an issue identfiied by the key JRA-9 would be like:
https://jira.atlassian.com/rest/api/latest/issue/JRA-9
Using JQL Language (syntax)
https://jira.mt-ag.com/rest/api/2/search?jql=project=BP
Returning values in JSON Format (testable also in browser)
12
REST-Webservice
16. Webservices
Getting existing ACL Entries
Important for ACL
Using Web Service References (shared
components or the APEX_WEB_SERVICE
(package)
principal = APEX_050000
using utl_http or other packages calling
external resources
principal = my_schema_name
16
ACL select a.acl
,a.host
,a.lower_port
,a.upper_port
,p.principal
,p.privilege
,p.is_grant
,to_char(p.start_date
,'DD-MON-YYYY') as start_date
,to_char(p.end_date
,'DD-MON-YYYY') as end_date
from dba_network_acl_privileges p
left join dba_network_acls a on a.acl = p.acl
18. Webservices
calling https:
To solve this problem, you have to get the certificates which are used by the server which
runs Jira
Getting certificate
use your browser and call the URL from the REST-Webservice or even from Jira
click on the lock symbol
click show certificate
18
exporting certificate
ORA-29273: HTTP request failed
ORA-29024: Certificate validation failure
20. Webservices
use the Oracle Wallet Manager (OWM) to import the certificate
run ORACLE_HOMEbinowm.cl (on windows a link is created)
Import of the certificate is also possible using the command line
create a wallet for the certificate using a path like this
ORACLE_BASEadmin<SID><name_wallet>
Use automatic login for your wallet (otherwise you have to use the wallet always with your
password in your plsql code)
20
importing certificate
22. Webservices
Shared Components
Web Service References
Create
Problems
based on single items
authentification
result as CLOB
only in Collection.
No support in
apex_items
report columns
JSON Format
23
Web Service Reference
26. JSON
convert clob
to JSON object
looping entries
get value
27
processing
l_values apex_json.t_values;
….
apex_json.parse(p_values => l_values
,p_source => l_clob);
for i in 1 .. apex_json.get_count(p_values => l_values
,p_path => '.')
loop … end loop
l_jira_issue.key := apex_json.get_varchar2(p_values => pi_json_issue
,p_path => 'key');
l_jira_issue.timespent := apex_json.get_number(p_values => pi_json_issue
,p_path => 'fields.timespent');
27. JSON
Number as String
you have to convert
Datetime as String
Converting with
apex_json.get_date
doesn‘t work because
of format
custom fields
in Jira are named like
customfield_xxxxx
28
special cases
"id": "17149"
"created": "2015-11-03T13:48:16.630+0100"
l_timestamp := to_timestamp_tz(pi_string
,'YYYY-MM-DD"T"hh24:mi:ss.FF3TZHTZM');
l_string := to_char(l_timestamp
,'yyyy.mm.dd hh24:mi:ss');
l_date := to_date(l_string
,'yyyy.mm.dd hh24:mi:ss');
apex_json.get_varchar2(p_values => pi_json_issue
,p_path => 'fields.customfield_10000');
28. JSON
Time worked / Worklog not with information by day encapsuleted in issue
you have call the worklog for every single ticket by one REST Call
29
special cases
for i in 1 .. apex_json.get_count(p_values => l_values, p_path => 'issues')
loop
l_rest_response := make_rest_request(pi_url => pi_jira_base_url || c_jira_rest_base_path || '/issue/' ||
apex_json.get_varchar2(p_values => l_values, p_path => 'issues[' || i || '].key'
,pi_username => pi_username
,pi_password => pi_password);
apex_json.parse(p_values => l_values_issue, p_source => l_rest_response);
l_jira_issue := get_issue_from_json(pi_json_issue => l_values_issue);
for j in 1 .. apex_json.get_count(p_values => l_values_issue
,p_path => 'fields.worklog.worklogs')
loop
l_jira_issue_worklog := get_issue_worklog_from_json(pi_json_issue_worklog => l_values_issue
,pi_path => 'fields.worklog.worklogs[' || j || '].'
,pi_jira_issue_id => l_jira_issue.id
,pi_jira_issue_key => l_jira_issue.key);
pipe row(l_jira_issue_worklog);
29. JSON
transform JSON into type
easier to use
Transformation in package instead APEX
testing possible by using sql
Entities defined as column names
documentation von
CollectionSpalte – JSON – Spaltenname im Type
using table function based on defined types
30
processing create or replace type t_jira_issue force as object
(
-- { id: "16276"
-- c001
id number, -- Jira Issue ID
-- { self: https://jira.mt-
ag.com/rest/api/2/issue/16276
-- c003
url_json varchar2(32767), -- c003 - JSON URL
-- { key: "UITFPP-1057„
-- c001
key varchar2(32767), -- Issue Key
select *
from table(jira_rest_ws_pkg.get_projects(pi_base_url => 'https://jira.atlassian.com'))
30. APEX
using APEX_COLLECTIONS
not every search means new webservice call
loading page doesn‘t call a webservice
APEX itself relies also on collections when working with Web Service References
problem authentication for webservice call
every call needs a username & password
using Web Service Reference it‘s inconvenient
using Application Items instead
when logging into the apex application password is saved on server-side by application item
attention the password value is visible in session state
31
32. Conclusion
complexity is huge because of many different technical aspects
all important key facts are calculateable
transforming JSON in JavaScript or PL/SQL is not easy in the beginning
first time parsing JSON even with APEX_JSON needs practice
remember in 12c you can directly parse JSON by SQL
Using APEX integrated „Web Service Reference“ only for simple examples
33
From April 26th to 28th, 2016, the second edition of APEX Connect will take place in Berlin.
Due to the positive feedback this year, there will be an extra day: The conference will be three days long.
April 26th: Focus on PL/SQL
April 27th - 28th: Full range of APEX programming
There will again be many great submissions and topics.
Main topics
Project Management & Methods
Operation
Web technology
Application Development
The conference program is in completion and will be released in spring.
The top speaker of the PL/SQL and APEX scene will be there.
David Peake
Patrick Wolf
Anton Nielsen
Martin Giffy D'Souza
Roger Troller
Jürgen Sieben
Olaf Jessensky
Chris Saxon
In addition to the lecture program, the following activities are planned:
Workshops
Unconference sessions
Many networking opportunities
At the moment, the early bird prices still apply. The sale of the exhibition is already running.