APEX connects Jira

Oliver Lemm

APEX World

07.03.2016

Facts & Figures

Independent Technology Housewith Cross-Industry Expertise

HeadquarterRatingen

(North Rhine – Westphalia)

240 Employees

Founded1994

BranchesDortmund, Cologne,

Frankfurt

Top Company for Trainees &

Students

Privately-Owned

Corporation

Oracle Platinum Partner

24 Mio. Euro Revenue

2

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

Agenda

1. Motivation

2. Jira

3. Webservices

4. JSON

5. Livedemo

4

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“

5

requirements

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

6

7

Jira

8

Workflow

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“

9

Integrated features

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

10

lack of features

Jira

§ API documentation for Jira REST-Webserviceshttps://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)

11

REST-Webservice

Jira

12

JQL

https://jira.mt-ag.com/rest/api/2/search?jql=project=BP

Jira

§ addional information when getting REST-Webservice Result

§ Default max 50 entries§ 1. solution: add parameter &maxResults=XXX

§ 2. solution: add Parameter &startAt=50

§ Sort the results

§ If no Authentication needed, don‘t submit username/password -> you get Unauthorized(401)

13

REST-Webservice

"expand":"schema,names","startAt":0,"maxResults":50,"total":827,"issues":[….]}

https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP&maxResults=1000

https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP&startAt=50

https://jira.mt-ag.com/rest/api/latest/search?jql=project=BP+order+by+duedate

Webservices

§ getting Error:

§ Example: https://jira.atlassian.com/rest/api/latest/issue/JRA-9

14

ACL

ORA-29273: HTTP request failed ORA-24247: network access denied by access control list (ACL)

begindbms_network_acl_admin.create_acl(acl => 'jira.atlassian.com.xml'

,description => 'An ACL for Calling REST Webservices.',principal => l_principal,is_grant => true,privilege => 'connect',start_date => systimestamp,end_date => null);

dbms_network_acl_admin.assign_acl(acl => 'jira.atlassian.com.xml',host => 'jira.atlassian.com',lower_port => 443,upper_port => 443);

commit;end;

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 callingexternal resources§ principal = my_schema_name

15

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_datefrom dba_network_acl_privileges pleft join dba_network_acls a on a.acl = p.acl

Webservices

16

exporting certificate

Webservices

§ calling https:

§ To solve this problem, you have to get the certificates which are used by the server whichruns 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

17

exporting certificate

ORA-29273: HTTP request failed ORA-29024: Certificate validation failure

Webservices

18

importing certificate

Webservices

§ use the Oracle Wallet Manager (OWM) to import the certificate§ run ORACLE_HOME\bin\owm.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 thisORACLE_BASE\admin\<SID>\<name_wallet>

§ Use automatic login for your wallet (otherwise you have to use the wallet always with yourpassword in your plsql code)

19

importing certificate

Webservice

§ APEX documentationhttp://docs.oracle.com/cd/E59726_01/doc.50/e39151/adm_wrkspc002.htm#BABHEHAG

§ Login into your INTERNAL WorkspaceØManage InstanceØInstance SettingsØWallet

20

certificate in APEX

Webservices

§ still getting error like:

§ The ACL Syntax has been changed so look up changed ACL behavior for 12c.

21

12c

ORA-29273: HTTP request failedORA-12541: TNS:no listener

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

22

Web Service Reference

Webservices

23

Web Service Reference

Webservice

§ Call REST

§ p_http_method GET, HEAD, POST, PUT, DELETE

§ Username & Password supporting Basic Authentication

§ Parameter if parameter beside the URL itself are needed

24

APEX_WEB_SERVICE

l_clob := apex_web_service.make_rest_request(p_url => 'https://jira.atlassian.com/rest/api/latest/issue/JRA-

9',p_http_method => 'GET',p_wallet_path => 'file:C:\oracle\admin\orcl\mein_wallet',p_username => 'lemmo',p_password => '123456 '‚,p_parm_name => apex_util.string_to_table('param1:param2'),,p_parm_value => apex_util.string_to_table('val1:val2')

);

JSON

§ Datentypen§ String§ "QS - Demo Feature" § "2015-11-03T13:48:16.630+0100"

§ Number§ 20

§ Boolean§ true / false

§ Null§ null

§ Array§ [ {…}, {…}]

25

format

{"id": "17149","self": "https://jira.mt-ag.com/rest/api/latest/issue/17149","key": "BP-7","fields": {

“summary": "QS - Demo Feature","progress": {

"progress": �19800,"total": �19800,"percent": �100

}, "created": "2015-11-03T13:48:16.630+0100",worklog": {

"startAt": �0,"maxResults": �20,"total": �2,"worklogs": [

{ ... },{ ... }

]}

}}

JSON

§ convert clobto JSON object

§ looping entries

§ get value

26

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');

JSON

§ Number as String§ you have to convert

§ Datetime as String§ Converting with

apex_json.get_datedoesn‘t work becauseof format

§ custom fieldsin Jira are named likecustomfield_xxxxx

27

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');

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

28

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);

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

29

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'))

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

30

APEX

31

Live demo

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 practiceremember in 12c you can directly parse JSON by SQL

§ Using APEX integrated „Web Service Reference“ only for simple examples

32

@OliverLemm

http://oliverlemm.blogspot.de

http://de.linkedin.com/in/OliverLemm

https://www.xing.com/profile/Oliver_Lemm

Questions?